1.. _context: 2 3Context 4======= 5 6A Gallium rendering context encapsulates the state which effects 3D 7rendering such as blend state, depth/stencil state, texture samplers, 8etc. 9 10Note that resource/texture allocation is not per-context but per-screen. 11 12 13Methods 14------- 15 16CSO State 17^^^^^^^^^ 18 19All Constant State Object (CSO) state is created, bound, and destroyed, 20with triplets of methods that all follow a specific naming scheme. 21For example, ``create_blend_state``, ``bind_blend_state``, and 22``destroy_blend_state``. 23 24CSO objects handled by the context object: 25 26* :ref:`Blend`: ``*_blend_state`` 27* :ref:`Sampler`: Texture sampler states are bound separately for fragment, 28 vertex, geometry and compute shaders with the ``bind_sampler_states`` 29 function. The ``start`` and ``num_samplers`` parameters indicate a range 30 of samplers to change. NOTE: at this time, start is always zero and 31 the CSO module will always replace all samplers at once (no sub-ranges). 32 This may change in the future. 33* :ref:`Rasterizer`: ``*_rasterizer_state`` 34* :ref:`depth-stencil-alpha`: ``*_depth_stencil_alpha_state`` 35* :ref:`Shader`: These are create, bind and destroy methods for vertex, 36 fragment and geometry shaders. 37* :ref:`vertexelements`: ``*_vertex_elements_state`` 38 39 40Resource Binding State 41^^^^^^^^^^^^^^^^^^^^^^ 42 43This state describes how resources in various flavors (textures, 44buffers, surfaces) are bound to the driver. 45 46 47* ``set_constant_buffer`` sets a constant buffer to be used for a given shader 48 type. index is used to indicate which buffer to set (some APIs may allow 49 multiple ones to be set, and binding a specific one later, though drivers 50 are mostly restricted to the first one right now). 51 If take_ownership is true, the buffer reference is passed to the driver, so 52 that the driver doesn't have to increment the reference count. 53 54* ``set_inlinable_constants`` sets inlinable constants for constant buffer 0. 55 56These are constants that the driver would like to inline in the IR 57of the current shader and recompile it. Drivers can determine which 58constants they prefer to inline in finalize_nir and store that 59information in shader_info::*inlinable_uniform*. When the state tracker 60or frontend uploads constants to a constant buffer, it can pass 61inlinable constants separately via this call. 62 63Any ``set_constant_buffer`` call invalidates inlinable constants, so 64``set_inlinable_constants`` must be called after it. Binding a shader also 65invalidates this state. 66 67There is no ``PIPE_CAP`` for this. Drivers shouldn't set the shader_info 68fields if they don't implement ``set_inlinable_constants``. 69 70* ``set_framebuffer_state`` 71 72* ``set_vertex_buffers`` 73 74 75Non-CSO State 76^^^^^^^^^^^^^ 77 78These pieces of state are too small, variable, and/or trivial to have CSO 79objects. They all follow simple, one-method binding calls, e.g. 80``set_blend_color``. 81 82* ``set_stencil_ref`` sets the stencil front and back reference values 83 which are used as comparison values in stencil test. 84* ``set_blend_color`` 85* ``set_sample_mask`` sets the per-context multisample sample mask. Note 86 that this takes effect even if multisampling is not explicitly enabled if 87 the framebuffer surface(s) are multisampled. Also, this mask is AND-ed 88 with the optional fragment shader sample mask output (when emitted). 89* ``set_sample_locations`` sets the sample locations used for rasterization. 90 ```get_sample_position``` still returns the default locations. When NULL, 91 the default locations are used. 92* ``set_min_samples`` sets the minimum number of samples that must be run. 93* ``set_clip_state`` 94* ``set_polygon_stipple`` 95* ``set_scissor_states`` sets the bounds for the scissor test, which culls 96 pixels before blending to render targets. If the :ref:`Rasterizer` does 97 not have the scissor test enabled, then the scissor bounds never need to 98 be set since they will not be used. Note that scissor xmin and ymin are 99 inclusive, but xmax and ymax are exclusive. The inclusive ranges in x 100 and y would be [xmin..xmax-1] and [ymin..ymax-1]. The number of scissors 101 should be the same as the number of set viewports and can be up to 102 PIPE_MAX_VIEWPORTS. 103* ``set_viewport_states`` 104* ``set_window_rectangles`` sets the window rectangles to be used for 105 rendering, as defined by GL_EXT_window_rectangles. There are two 106 modes - include and exclude, which define whether the supplied 107 rectangles are to be used for including fragments or excluding 108 them. All of the rectangles are ORed together, so in exclude mode, 109 any fragment inside any rectangle would be culled, while in include 110 mode, any fragment outside all rectangles would be culled. xmin/ymin 111 are inclusive, while xmax/ymax are exclusive (same as scissor states 112 above). Note that this only applies to draws, not clears or 113 blits. (Blits have their own way to pass the requisite rectangles 114 in.) 115* ``set_tess_state`` configures the default tessellation parameters: 116 117 * ``default_outer_level`` is the default value for the outer tessellation 118 levels. This corresponds to GL's ``PATCH_DEFAULT_OUTER_LEVEL``. 119 * ``default_inner_level`` is the default value for the inner tessellation 120 levels. This corresponds to GL's ``PATCH_DEFAULT_INNER_LEVEL``. 121* ``set_patch_vertices`` sets the number of vertices per input patch 122 for tessellation. 123 124* ``set_debug_callback`` sets the callback to be used for reporting 125 various debug messages, eventually reported via KHR_debug and 126 similar mechanisms. 127 128Samplers 129^^^^^^^^ 130 131pipe_sampler_state objects control how textures are sampled 132(coordinate wrap modes, interpolation modes, etc). Note that unless 133``PIPE_CAP_TEXTURE_BUFFER_SAMPLER`` is enabled, samplers are not used for 134texture buffer objects. That is, pipe_context::bind_sampler_views() 135will not bind a sampler if the corresponding sampler view refers to a 136PIPE_BUFFER resource. 137 138Sampler Views 139^^^^^^^^^^^^^ 140 141These are the means to bind textures to shader stages. To create one, specify 142its format, swizzle and LOD range in sampler view template. 143 144If texture format is different than template format, it is said the texture 145is being cast to another format. Casting can be done only between compatible 146formats, that is formats that have matching component order and sizes. 147 148Swizzle fields specify the way in which fetched texel components are placed 149in the result register. For example, ``swizzle_r`` specifies what is going to be 150placed in first component of result register. 151 152The ``first_level`` and ``last_level`` fields of sampler view template specify 153the LOD range the texture is going to be constrained to. Note that these 154values are in addition to the respective min_lod, max_lod values in the 155pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip 156level used for sampling from the resource is effectively the fifth). 157 158The ``first_layer`` and ``last_layer`` fields specify the layer range the 159texture is going to be constrained to. Similar to the LOD range, this is added 160to the array index which is used for sampling. 161 162* ``set_sampler_views`` binds an array of sampler views to a shader stage. 163 Every binding point acquires a reference 164 to a respective sampler view and releases a reference to the previous 165 sampler view. 166 167 Sampler views outside of ``[start_slot, start_slot + num_views)`` are 168 unmodified. If ``views`` is NULL, the behavior is the same as if 169 ``views[n]`` was NULL for the entire range, i.e. releasing the reference 170 for all the sampler views in the specified range. 171 172* ``create_sampler_view`` creates a new sampler view. ``texture`` is associated 173 with the sampler view which results in sampler view holding a reference 174 to the texture. Format specified in template must be compatible 175 with texture format. 176 177* ``sampler_view_destroy`` destroys a sampler view and releases its reference 178 to associated texture. 179 180Hardware Atomic buffers 181^^^^^^^^^^^^^^^^^^^^^^^ 182 183Buffers containing hw atomics are required to support the feature 184on some drivers. 185 186Drivers that require this need to fill the ``set_hw_atomic_buffers`` method. 187 188Shader Resources 189^^^^^^^^^^^^^^^^ 190 191Shader resources are textures or buffers that may be read or written 192from a shader without an associated sampler. This means that they 193have no support for floating point coordinates, address wrap modes or 194filtering. 195 196There are 2 types of shader resources: buffers and images. 197 198Buffers are specified using the ``set_shader_buffers`` method. 199 200Images are specified using the ``set_shader_images`` method. When binding 201images, the ``level``, ``first_layer`` and ``last_layer`` pipe_image_view 202fields specify the mipmap level and the range of layers the image will be 203constrained to. 204 205Surfaces 206^^^^^^^^ 207 208These are the means to use resources as color render targets or depthstencil 209attachments. To create one, specify the mip level, the range of layers, and 210the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET). 211Note that layer values are in addition to what is indicated by the geometry 212shader output variable XXX_FIXME (that is if first_layer is 3 and geometry 213shader indicates index 2, the 5th layer of the resource will be used). These 214first_layer and last_layer parameters will only be used for 1d array, 2d array, 215cube, and 3d textures otherwise they are 0. 216 217* ``create_surface`` creates a new surface. 218 219* ``surface_destroy`` destroys a surface and releases its reference to the 220 associated resource. 221 222Stream output targets 223^^^^^^^^^^^^^^^^^^^^^ 224 225Stream output, also known as transform feedback, allows writing the primitives 226produced by the vertex pipeline to buffers. This is done after the geometry 227shader or vertex shader if no geometry shader is present. 228 229The stream output targets are views into buffer resources which can be bound 230as stream outputs and specify a memory range where it's valid to write 231primitives. The pipe driver must implement memory protection such that any 232primitives written outside of the specified memory range are discarded. 233 234Two stream output targets can use the same resource at the same time, but 235with a disjoint memory range. 236 237Additionally, the stream output target internally maintains the offset 238into the buffer which is incremented every time something is written to it. 239The internal offset is equal to how much data has already been written. 240It can be stored in device memory and the CPU actually doesn't have to query 241it. 242 243The stream output target can be used in a draw command to provide 244the vertex count. The vertex count is derived from the internal offset 245discussed above. 246 247* ``create_stream_output_target`` create a new target. 248 249* ``stream_output_target_destroy`` destroys a target. Users of this should 250 use pipe_so_target_reference instead. 251 252* ``set_stream_output_targets`` binds stream output targets. The parameter 253 offset is an array which specifies the internal offset of the buffer. The 254 internal offset is, besides writing, used for reading the data during the 255 draw_auto stage, i.e. it specifies how much data there is in the buffer 256 for the purposes of the draw_auto stage. -1 means the buffer should 257 be appended to, and everything else sets the internal offset. 258 259* ``stream_output_target_offset`` Retrieve the internal stream offset from 260 an streamout target. This is used to implement Vulkan pause/resume support 261 which needs to pass the internal offset to the API. 262 263NOTE: The currently-bound vertex or geometry shader must be compiled with 264the properly-filled-in structure pipe_stream_output_info describing which 265outputs should be written to buffers and how. The structure is part of 266pipe_shader_state. 267 268Clearing 269^^^^^^^^ 270 271Clear is one of the most difficult concepts to nail down to a single 272interface (due to both different requirements from APIs and also driver/hw 273specific differences). 274 275``clear`` initializes some or all of the surfaces currently bound to 276the framebuffer to particular RGBA, depth, or stencil values. 277Currently, this does not take into account color or stencil write masks (as 278used by GL), and always clears the whole surfaces (no scissoring as used by 279GL clear or explicit rectangles like d3d9 uses). It can, however, also clear 280only depth or stencil in a combined depth/stencil surface. 281If a surface includes several layers then all layers will be cleared. 282 283``clear_render_target`` clears a single color rendertarget with the specified 284color value. While it is only possible to clear one surface at a time (which can 285include several layers), this surface need not be bound to the framebuffer. 286If render_condition_enabled is false, any current rendering condition is ignored 287and the clear will be unconditional. 288 289``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface 290with the specified depth and stencil values (for combined depth/stencil buffers, 291it is also possible to only clear one or the other part). While it is only 292possible to clear one surface at a time (which can include several layers), 293this surface need not be bound to the framebuffer. 294If render_condition_enabled is false, any current rendering condition is ignored 295and the clear will be unconditional. 296 297``clear_texture`` clears a non-PIPE_BUFFER resource's specified level 298and bounding box with a clear value provided in that resource's native 299format. 300 301``clear_buffer`` clears a PIPE_BUFFER resource with the specified clear value 302(which may be multiple bytes in length). Logically this is a memset with a 303multi-byte element value starting at offset bytes from resource start, going 304for size bytes. It is guaranteed that size % clear_value_size == 0. 305 306Evaluating Depth Buffers 307^^^^^^^^^^^^^^^^^^^^^^^^ 308 309``evaluate_depth_buffer`` is a hint to decompress the current depth buffer 310assuming the current sample locations to avoid problems that could arise when 311using programmable sample locations. 312 313If a depth buffer is rendered with different sample location state than 314what is current at the time of reading the depth buffer, the values may differ 315because depth buffer compression can depend the sample locations. 316 317 318Uploading 319^^^^^^^^^ 320 321For simple single-use uploads, use ``pipe_context::stream_uploader`` or 322``pipe_context::const_uploader``. The latter should be used for uploading 323constants, while the former should be used for uploading everything else. 324PIPE_USAGE_STREAM is implied in both cases, so don't use the uploaders 325for static allocations. 326 327Usage: 328 329Call u_upload_alloc or u_upload_data as many times as you want. After you are 330done, call u_upload_unmap. If the driver doesn't support persistent mappings, 331u_upload_unmap makes sure the previously mapped memory is unmapped. 332 333Gotchas: 334- Always fill the memory immediately after u_upload_alloc. Any following call 335to u_upload_alloc and u_upload_data can unmap memory returned by previous 336u_upload_alloc. 337- Don't interleave calls using stream_uploader and const_uploader. If you use 338one of them, do the upload, unmap, and only then can you use the other one. 339 340 341Drawing 342^^^^^^^ 343 344``draw_vbo`` draws a specified primitive. The primitive mode and other 345properties are described by ``pipe_draw_info``. 346 347The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the 348the mode of the primitive and the vertices to be fetched, in the range between 349``start`` to ``start``+``count``-1, inclusive. 350 351Every instance with instanceID in the range between ``start_instance`` and 352``start_instance``+``instance_count``-1, inclusive, will be drawn. 353 354If ``index_size`` != 0, all vertex indices will be looked up from the index 355buffer. 356 357In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower 358and upper bound of the indices contained in the index buffer inside the range 359between ``start`` to ``start``+``count``-1. This allows the driver to 360determine which subset of vertices will be referenced during te draw call 361without having to scan the index buffer. Providing a over-estimation of the 362the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and 3630xffffffff respectively, must give exactly the same rendering, albeit with less 364performance due to unreferenced vertex buffers being unnecessarily DMA'ed or 365processed. Providing a underestimation of the true bounds will result in 366undefined behavior, but should not result in program or system failure. 367 368In case of non-indexed draw, ``min_index`` should be set to 369``start`` and ``max_index`` should be set to ``start``+``count``-1. 370 371``index_bias`` is a value added to every vertex index after lookup and before 372fetching vertex attributes. 373 374When drawing indexed primitives, the primitive restart index can be 375used to draw disjoint primitive strips. For example, several separate 376line strips can be drawn by designating a special index value as the 377restart index. The ``primitive_restart`` flag enables/disables this 378feature. The ``restart_index`` field specifies the restart index value. 379 380When primitive restart is in use, array indexes are compared to the 381restart index before adding the index_bias offset. 382 383If a given vertex element has ``instance_divisor`` set to 0, it is said 384it contains per-vertex data and effective vertex attribute address needs 385to be recalculated for every index. 386 387 attribAddr = ``stride`` * index + ``src_offset`` 388 389If a given vertex element has ``instance_divisor`` set to non-zero, 390it is said it contains per-instance data and effective vertex attribute 391address needs to recalculated for every ``instance_divisor``-th instance. 392 393 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset`` 394 395In the above formulas, ``src_offset`` is taken from the given vertex element 396and ``stride`` is taken from a vertex buffer associated with the given 397vertex element. 398 399The calculated attribAddr is used as an offset into the vertex buffer to 400fetch the attribute data. 401 402The value of ``instanceID`` can be read in a vertex shader through a system 403value register declared with INSTANCEID semantic name. 404 405 406Queries 407^^^^^^^ 408 409Queries gather some statistic from the 3D pipeline over one or more 410draws. Queries may be nested, though not all gallium frontends exercise this. 411 412Queries can be created with ``create_query`` and deleted with 413``destroy_query``. To start a query, use ``begin_query``, and when finished, 414use ``end_query`` to end the query. 415 416``create_query`` takes a query type (``PIPE_QUERY_*``), as well as an index, 417which is the vertex stream for ``PIPE_QUERY_PRIMITIVES_GENERATED`` and 418``PIPE_QUERY_PRIMITIVES_EMITTED``, and allocates a query structure. 419 420``begin_query`` will clear/reset previous query results. 421 422``get_query_result`` is used to retrieve the results of a query. If 423the ``wait`` parameter is TRUE, then the ``get_query_result`` call 424will block until the results of the query are ready (and TRUE will be 425returned). Otherwise, if the ``wait`` parameter is FALSE, the call 426will not block and the return value will be TRUE if the query has 427completed or FALSE otherwise. 428 429``get_query_result_resource`` is used to store the result of a query into 430a resource without synchronizing with the CPU. This write will optionally 431wait for the query to complete, and will optionally write whether the value 432is available instead of the value itself. 433 434``set_active_query_state`` Set whether all current non-driver queries except 435TIME_ELAPSED are active or paused. 436 437The interface currently includes the following types of queries: 438 439``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which 440are written to the framebuffer without being culled by 441:ref:`depth-stencil-alpha` testing or shader KILL instructions. 442The result is an unsigned 64-bit integer. 443This query can be used with ``render_condition``. 444 445In cases where a boolean result of an occlusion query is enough, 446``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like 447``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean 448value of FALSE for cases where COUNTER would result in 0 and TRUE 449for all other cases. 450This query can be used with ``render_condition``. 451 452In cases where a conservative approximation of an occlusion query is enough, 453``PIPE_QUERY_OCCLUSION_PREDICATE_CONSERVATIVE`` should be used. It behaves 454like ``PIPE_QUERY_OCCLUSION_PREDICATE``, except that it may return TRUE in 455additional, implementation-dependent cases. 456This query can be used with ``render_condition``. 457 458``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds, 459the context takes to perform operations. 460The result is an unsigned 64-bit integer. 461 462``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp, 463scaled to nanoseconds, recorded after all commands issued prior to 464``end_query`` have been processed. 465This query does not require a call to ``begin_query``. 466The result is an unsigned 64-bit integer. 467 468``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check the 469internal timer resolution and whether the timestamp counter has become 470unreliable due to things like throttling etc. - only if this is FALSE 471a timestamp query (within the timestamp_disjoint query) should be trusted. 472The result is a 64-bit integer specifying the timer resolution in Hz, 473followed by a boolean value indicating whether the timestamp counter 474is discontinuous or disjoint. 475 476``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating 477the number of primitives processed by the pipeline (regardless of whether 478stream output is active or not). 479 480``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating 481the number of primitives written to stream output buffers. 482 483``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to 484the result of 485``PIPE_QUERY_PRIMITIVES_EMITTED`` and 486the number of primitives that would have been written to stream output buffers 487if they had infinite space available (primitives_storage_needed), in this order. 488XXX the 2nd value is equivalent to ``PIPE_QUERY_PRIMITIVES_GENERATED`` but it is 489unclear if it should be increased if stream output is not active. 490 491``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating 492whether a selected stream output target has overflowed as a result of the 493commands issued between ``begin_query`` and ``end_query``. 494This query can be used with ``render_condition``. The output stream is 495selected by the stream number passed to ``create_query``. 496 497``PIPE_QUERY_SO_OVERFLOW_ANY_PREDICATE`` returns a boolean value indicating 498whether any stream output target has overflowed as a result of the commands 499issued between ``begin_query`` and ``end_query``. This query can be used 500with ``render_condition``, and its result is the logical OR of multiple 501``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` queries, one for each stream output 502target. 503 504``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether 505all commands issued before ``end_query`` have completed. However, this 506does not imply serialization. 507This query does not require a call to ``begin_query``. 508 509``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following 51064-bit integers: 511Number of vertices read from vertex buffers. 512Number of primitives read from vertex buffers. 513Number of vertex shader threads launched. 514Number of geometry shader threads launched. 515Number of primitives generated by geometry shaders. 516Number of primitives forwarded to the rasterizer. 517Number of primitives rasterized. 518Number of fragment shader threads launched. 519Number of tessellation control shader threads launched. 520Number of tessellation evaluation shader threads launched. 521If a shader type is not supported by the device/driver, 522the corresponding values should be set to 0. 523 524``PIPE_QUERY_PIPELINE_STATISTICS_SINGLE`` returns a single counter from 525the ``PIPE_QUERY_PIPELINE_STATISTICS`` group. The specific counter must 526be selected when calling ``create_query`` by passing one of the 527``PIPE_STAT_QUERY`` enums as the query's ``index``. 528 529Gallium does not guarantee the availability of any query types; one must 530always check the capabilities of the :ref:`Screen` first. 531 532 533Conditional Rendering 534^^^^^^^^^^^^^^^^^^^^^ 535 536A drawing command can be skipped depending on the outcome of a query 537(typically an occlusion query, or streamout overflow predicate). 538The ``render_condition`` function specifies the query which should be checked 539prior to rendering anything. Functions always honoring render_condition include 540(and are limited to) draw_vbo and clear. 541The blit, clear_render_target and clear_depth_stencil functions (but 542not resource_copy_region, which seems inconsistent) can also optionally honor 543the current render condition. 544 545If ``render_condition`` is called with ``query`` = NULL, conditional 546rendering is disabled and drawing takes place normally. 547 548If ``render_condition`` is called with a non-null ``query`` subsequent 549drawing commands will be predicated on the outcome of the query. 550Commands will be skipped if ``condition`` is equal to the predicate result 551(for non-boolean queries such as OCCLUSION_QUERY, zero counts as FALSE, 552non-zero as TRUE). 553 554If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the 555query to complete before deciding whether to render. 556 557If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet 558completed, the drawing command will be executed normally. If the query 559has completed, drawing will be predicated on the outcome of the query. 560 561If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or 562PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above 563for the non-REGION modes but in the case that an occlusion query returns 564a non-zero result, regions which were occluded may be ommitted by subsequent 565drawing commands. This can result in better performance with some GPUs. 566Normally, if the occlusion query returned a non-zero result subsequent 567drawing happens normally so fragments may be generated, shaded and 568processed even where they're known to be obscured. 569 570The ''render_condition_mem'' function specifies the drawing is dependant 571on a value in memory. A buffer resource and offset denote which 32-bit 572value to use for the query. This is used for Vulkan API. 573 574Flushing 575^^^^^^^^ 576 577``flush`` 578 579PIPE_FLUSH_END_OF_FRAME: Whether the flush marks the end of frame. 580 581PIPE_FLUSH_DEFERRED: It is not required to flush right away, but it is required 582to return a valid fence. If fence_finish is called with the returned fence 583and the context is still unflushed, and the ctx parameter of fence_finish is 584equal to the context where the fence was created, fence_finish will flush 585the context. 586 587PIPE_FLUSH_ASYNC: The flush is allowed to be asynchronous. Unlike 588``PIPE_FLUSH_DEFERRED``, the driver must still ensure that the returned fence 589will finish in finite time. However, subsequent operations in other contexts of 590the same screen are no longer guaranteed to happen after the flush. Drivers 591which use this flag must implement pipe_context::fence_server_sync. 592 593PIPE_FLUSH_HINT_FINISH: Hints to the driver that the caller will immediately 594wait for the returned fence. 595 596Additional flags may be set together with ``PIPE_FLUSH_DEFERRED`` for even 597finer-grained fences. Note that as a general rule, GPU caches may not have been 598flushed yet when these fences are signaled. Drivers are free to ignore these 599flags and create normal fences instead. At most one of the following flags can 600be specified: 601 602PIPE_FLUSH_TOP_OF_PIPE: The fence should be signaled as soon as the next 603command is ready to start executing at the top of the pipeline, before any of 604its data is actually read (including indirect draw parameters). 605 606PIPE_FLUSH_BOTTOM_OF_PIPE: The fence should be signaled as soon as the previous 607command has finished executing on the GPU entirely (but data written by the 608command may still be in caches and inaccessible to the CPU). 609 610 611``flush_resource`` 612 613Flush the resource cache, so that the resource can be used 614by an external client. Possible usage: 615- flushing a resource before presenting it on the screen 616- flushing a resource if some other process or device wants to use it 617This shouldn't be used to flush caches if the resource is only managed 618by a single pipe_screen and is not shared with another process. 619(i.e. you shouldn't use it to flush caches explicitly if you want to e.g. 620use the resource for texturing) 621 622Fences 623^^^^^^ 624 625``pipe_fence_handle``, and related methods, are used to synchronize 626execution between multiple parties. Examples include CPU <-> GPU synchronization, 627renderer <-> windowing system, multiple external APIs, etc. 628 629A ``pipe_fence_handle`` can either be 'one time use' or 're-usable'. A 'one time use' 630fence behaves like a traditional GPU fence. Once it reaches the signaled state it 631is forever considered to be signaled. 632 633Once a re-usable ``pipe_fence_handle`` becomes signaled, it can be reset 634back into an unsignaled state. The ``pipe_fence_handle`` will be reset to 635the unsignaled state by performing a wait operation on said object, i.e. 636``fence_server_sync``. As a corollary to this behavior, a re-usable 637``pipe_fence_handle`` can only have one waiter. 638 639This behavior is useful in producer <-> consumer chains. It helps avoid 640unnecessarily sharing a new ``pipe_fence_handle`` each time a new frame is 641ready. Instead, the fences are exchanged once ahead of time, and access is synchronized 642through GPU signaling instead of direct producer <-> consumer communication. 643 644``fence_server_sync`` inserts a wait command into the GPU's command stream. 645 646``fence_server_signal`` inserts a signal command into the GPU's command stream. 647 648There are no guarantees that the wait/signal commands will be flushed when 649calling ``fence_server_sync`` or ``fence_server_signal``. An explicit 650call to ``flush`` is required to make sure the commands are emitted to the GPU. 651 652The Gallium implementation may implicitly ``flush`` the command stream during a 653``fence_server_sync`` or ``fence_server_signal`` call if necessary. 654 655Resource Busy Queries 656^^^^^^^^^^^^^^^^^^^^^ 657 658``is_resource_referenced`` 659 660 661 662Blitting 663^^^^^^^^ 664 665These methods emulate classic blitter controls. 666 667These methods operate directly on ``pipe_resource`` objects, and stand 668apart from any 3D state in the context. Blitting functionality may be 669moved to a separate abstraction at some point in the future. 670 671``resource_copy_region`` blits a region of a resource to a region of another 672resource, provided that both resources have the same format, or compatible 673formats, i.e., formats for which copying the bytes from the source resource 674unmodified to the destination resource will achieve the same effect of a 675textured quad blitter.. The source and destination may be the same resource, 676but overlapping blits are not permitted. 677This can be considered the equivalent of a CPU memcpy. 678 679``blit`` blits a region of a resource to a region of another resource, including 680scaling, format conversion, and up-/downsampling, as well as a destination clip 681rectangle (scissors) and window rectangles. It can also optionally honor the 682current render condition (but either way the blit itself never contributes 683anything to queries currently gathering data). 684As opposed to manually drawing a textured quad, this lets the pipe driver choose 685the optimal method for blitting (like using a special 2D engine), and usually 686offers, for example, accelerated stencil-only copies even where 687PIPE_CAP_SHADER_STENCIL_EXPORT is not available. 688 689 690Transfers 691^^^^^^^^^ 692 693These methods are used to get data to/from a resource. 694 695``transfer_map`` creates a memory mapping and the transfer object 696associated with it. 697The returned pointer points to the start of the mapped range according to 698the box region, not the beginning of the resource. If transfer_map fails, 699the returned pointer to the buffer memory is NULL, and the pointer 700to the transfer object remains unchanged (i.e. it can be non-NULL). 701 702``transfer_unmap`` remove the memory mapping for and destroy 703the transfer object. The pointer into the resource should be considered 704invalid and discarded. 705 706``texture_subdata`` and ``buffer_subdata`` perform a simplified 707transfer for simple writes. Basically transfer_map, data write, and 708transfer_unmap all in one. 709 710 711The box parameter to some of these functions defines a 1D, 2D or 3D 712region of pixels. This is self-explanatory for 1D, 2D and 3D texture 713targets. 714 715For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth 716fields refer to the array dimension of the texture. 717 718For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the 719faces of the cube map (z + depth <= 6). 720 721For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both 722the face and array dimension of the texture (face = z % 6, array = z / 6). 723 724 725.. _transfer_flush_region: 726 727transfer_flush_region 728%%%%%%%%%%%%%%%%%%%%% 729 730If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically 731be flushed on write or unmap. Flushes must be requested with 732``transfer_flush_region``. Flush ranges are relative to the mapped range, not 733the beginning of the resource. 734 735 736 737.. _texture_barrier: 738 739texture_barrier 740%%%%%%%%%%%%%%% 741 742This function flushes all pending writes to the currently-set surfaces and 743invalidates all read caches of the currently-set samplers. This can be used 744for both regular textures as well as for framebuffers read via FBFETCH. 745 746 747 748.. _memory_barrier: 749 750memory_barrier 751%%%%%%%%%%%%%%% 752 753This function flushes caches according to which of the PIPE_BARRIER_* flags 754are set. 755 756 757 758.. _resource_commit: 759 760resource_commit 761%%%%%%%%%%%%%%% 762 763This function changes the commit state of a part of a sparse resource. Sparse 764resources are created by setting the ``PIPE_RESOURCE_FLAG_SPARSE`` flag when 765calling ``resource_create``. Initially, sparse resources only reserve a virtual 766memory region that is not backed by memory (i.e., it is uncommitted). The 767``resource_commit`` function can be called to commit or uncommit parts (or all) 768of a resource. The driver manages the underlying backing memory. 769 770The contents of newly committed memory regions are undefined. Calling this 771function to commit an already committed memory region is allowed and leaves its 772content unchanged. Similarly, calling this function to uncommit an already 773uncommitted memory region is allowed. 774 775For buffers, the given box must be aligned to multiples of 776``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``. As an exception to this rule, if the size 777of the buffer is not a multiple of the page size, changing the commit state of 778the last (partial) page requires a box that ends at the end of the buffer 779(i.e., box->x + box->width == buffer->width0). 780 781 782 783.. _pipe_transfer: 784 785PIPE_MAP 786^^^^^^^^^^^^^ 787 788These flags control the behavior of a transfer object. 789 790``PIPE_MAP_READ`` 791 Resource contents read back (or accessed directly) at transfer create time. 792 793``PIPE_MAP_WRITE`` 794 Resource contents will be written back at transfer_unmap time (or modified 795 as a result of being accessed directly). 796 797``PIPE_MAP_DIRECTLY`` 798 a transfer should directly map the resource. May return NULL if not supported. 799 800``PIPE_MAP_DISCARD_RANGE`` 801 The memory within the mapped region is discarded. Cannot be used with 802 ``PIPE_MAP_READ``. 803 804``PIPE_MAP_DISCARD_WHOLE_RESOURCE`` 805 Discards all memory backing the resource. It should not be used with 806 ``PIPE_MAP_READ``. 807 808``PIPE_MAP_DONTBLOCK`` 809 Fail if the resource cannot be mapped immediately. 810 811``PIPE_MAP_UNSYNCHRONIZED`` 812 Do not synchronize pending operations on the resource when mapping. The 813 interaction of any writes to the map and any operations pending on the 814 resource are undefined. Cannot be used with ``PIPE_MAP_READ``. 815 816``PIPE_MAP_FLUSH_EXPLICIT`` 817 Written ranges will be notified later with :ref:`transfer_flush_region`. 818 Cannot be used with ``PIPE_MAP_READ``. 819 820``PIPE_MAP_PERSISTENT`` 821 Allows the resource to be used for rendering while mapped. 822 PIPE_RESOURCE_FLAG_MAP_PERSISTENT must be set when creating 823 the resource. 824 If COHERENT is not set, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER) 825 must be called to ensure the device can see what the CPU has written. 826 827``PIPE_MAP_COHERENT`` 828 If PERSISTENT is set, this ensures any writes done by the device are 829 immediately visible to the CPU and vice versa. 830 PIPE_RESOURCE_FLAG_MAP_COHERENT must be set when creating 831 the resource. 832 833Compute kernel execution 834^^^^^^^^^^^^^^^^^^^^^^^^ 835 836A compute program can be defined, bound or destroyed using 837``create_compute_state``, ``bind_compute_state`` or 838``destroy_compute_state`` respectively. 839 840Any of the subroutines contained within the compute program can be 841executed on the device using the ``launch_grid`` method. This method 842will execute as many instances of the program as elements in the 843specified N-dimensional grid, hopefully in parallel. 844 845The compute program has access to four special resources: 846 847* ``GLOBAL`` represents a memory space shared among all the threads 848 running on the device. An arbitrary buffer created with the 849 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the 850 ``set_global_binding`` method. 851 852* ``LOCAL`` represents a memory space shared among all the threads 853 running in the same working group. The initial contents of this 854 resource are undefined. 855 856* ``PRIVATE`` represents a memory space local to a single thread. 857 The initial contents of this resource are undefined. 858 859* ``INPUT`` represents a read-only memory space that can be 860 initialized at ``launch_grid`` time. 861 862These resources use a byte-based addressing scheme, and they can be 863accessed from the compute program by means of the LOAD/STORE TGSI 864opcodes. Additional resources to be accessed using the same opcodes 865may be specified by the user with the ``set_compute_resources`` 866method. 867 868In addition, normal texture sampling is allowed from the compute 869program: ``bind_sampler_states`` may be used to set up texture 870samplers for the compute stage and ``set_sampler_views`` may 871be used to bind a number of sampler views to it. 872 873Mipmap generation 874^^^^^^^^^^^^^^^^^ 875 876If PIPE_CAP_GENERATE_MIPMAP is true, ``generate_mipmap`` can be used 877to generate mipmaps for the specified texture resource. 878It replaces texel image levels base_level+1 through 879last_level for layers range from first_layer through last_layer. 880It returns TRUE if mipmap generation succeeds, otherwise it 881returns FALSE. Mipmap generation may fail when it is not supported 882for particular texture types or formats. 883 884Device resets 885^^^^^^^^^^^^^ 886 887Gallium frontends can query or request notifications of when the GPU 888is reset for whatever reason (application error, driver error). When 889a GPU reset happens, the context becomes unusable and all related state 890should be considered lost and undefined. Despite that, context 891notifications are single-shot, i.e. subsequent calls to 892``get_device_reset_status`` will return PIPE_NO_RESET. 893 894* ``get_device_reset_status`` queries whether a device reset has happened 895 since the last call or since the last notification by callback. 896* ``set_device_reset_callback`` sets a callback which will be called when 897 a device reset is detected. The callback is only called synchronously. 898 899Bindless 900^^^^^^^^ 901 902If PIPE_CAP_BINDLESS_TEXTURE is TRUE, the following ``pipe_context`` functions 903are used to create/delete bindless handles, and to make them resident in the 904current context when they are going to be used by shaders. 905 906* ``create_texture_handle`` creates a 64-bit unsigned integer texture handle 907 that is going to be directly used in shaders. 908* ``delete_texture_handle`` deletes a 64-bit unsigned integer texture handle. 909* ``make_texture_handle_resident`` makes a 64-bit unsigned texture handle 910 resident in the current context to be accessible by shaders for texture 911 mapping. 912* ``create_image_handle`` creates a 64-bit unsigned integer image handle that 913 is going to be directly used in shaders. 914* ``delete_image_handle`` deletes a 64-bit unsigned integer image handle. 915* ``make_image_handle_resident`` makes a 64-bit unsigned integer image handle 916 resident in the current context to be accessible by shaders for image loads, 917 stores and atomic operations. 918 919Using several contexts 920---------------------- 921 922Several contexts from the same screen can be used at the same time. Objects 923created on one context cannot be used in another context, but the objects 924created by the screen methods can be used by all contexts. 925 926Transfers 927^^^^^^^^^ 928A transfer on one context is not expected to synchronize properly with 929rendering on other contexts, thus only areas not yet used for rendering should 930be locked. 931 932A flush is required after transfer_unmap to expect other contexts to see the 933uploaded data, unless: 934 935* Using persistent mapping. Associated with coherent mapping, unmapping the 936 resource is also not required to use it in other contexts. Without coherent 937 mapping, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER) should be called on the 938 context that has mapped the resource. No flush is required. 939 940* Mapping the resource with PIPE_MAP_DIRECTLY. 941