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 and geometry samplers. Note that sampler states are set en masse. 29 If M is the max number of sampler units supported by the driver and N 30 samplers are bound with ``bind_fragment_sampler_states`` then sampler 31 units N..M-1 are considered disabled/NULL. 32* :ref:`Rasterizer`: ``*_rasterizer_state`` 33* :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state`` 34* :ref:`Shader`: These are create, bind and destroy methods for vertex, 35 fragment and geometry shaders. 36* :ref:`Vertex Elements`: ``*_vertex_elements_state`` 37 38 39Resource Binding State 40^^^^^^^^^^^^^^^^^^^^^^ 41 42This state describes how resources in various flavours (textures, 43buffers, surfaces) are bound to the driver. 44 45 46* ``set_constant_buffer`` sets a constant buffer to be used for a given shader 47 type. index is used to indicate which buffer to set (some apis may allow 48 multiple ones to be set, and binding a specific one later, though drivers 49 are mostly restricted to the first one right now). 50 51* ``set_framebuffer_state`` 52 53* ``set_vertex_buffers`` 54 55* ``set_index_buffer`` 56 57 58Non-CSO State 59^^^^^^^^^^^^^ 60 61These pieces of state are too small, variable, and/or trivial to have CSO 62objects. They all follow simple, one-method binding calls, e.g. 63``set_blend_color``. 64 65* ``set_stencil_ref`` sets the stencil front and back reference values 66 which are used as comparison values in stencil test. 67* ``set_blend_color`` 68* ``set_sample_mask`` 69* ``set_clip_state`` 70* ``set_polygon_stipple`` 71* ``set_scissor_state`` sets the bounds for the scissor test, which culls 72 pixels before blending to render targets. If the :ref:`Rasterizer` does 73 not have the scissor test enabled, then the scissor bounds never need to 74 be set since they will not be used. Note that scissor xmin and ymin are 75 inclusive, but xmax and ymax are exclusive. The inclusive ranges in x 76 and y would be [xmin..xmax-1] and [ymin..ymax-1]. 77* ``set_viewport_state`` 78 79 80Sampler Views 81^^^^^^^^^^^^^ 82 83These are the means to bind textures to shader stages. To create one, specify 84its format, swizzle and LOD range in sampler view template. 85 86If texture format is different than template format, it is said the texture 87is being cast to another format. Casting can be done only between compatible 88formats, that is formats that have matching component order and sizes. 89 90Swizzle fields specify they way in which fetched texel components are placed 91in the result register. For example, ``swizzle_r`` specifies what is going to be 92placed in first component of result register. 93 94The ``first_level`` and ``last_level`` fields of sampler view template specify 95the LOD range the texture is going to be constrained to. Note that these 96values are in addition to the respective min_lod, max_lod values in the 97pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip 98level used for sampling from the resource is effectively the fifth). 99 100The ``first_layer`` and ``last_layer`` fields specify the layer range the 101texture is going to be constrained to. Similar to the LOD range, this is added 102to the array index which is used for sampling. 103 104* ``set_fragment_sampler_views`` binds an array of sampler views to 105 fragment shader stage. Every binding point acquires a reference 106 to a respective sampler view and releases a reference to the previous 107 sampler view. If M is the maximum number of sampler units and N units 108 is passed to set_fragment_sampler_views, the driver should unbind the 109 sampler views for units N..M-1. 110 111* ``set_vertex_sampler_views`` binds an array of sampler views to vertex 112 shader stage. Every binding point acquires a reference to a respective 113 sampler view and releases a reference to the previous sampler view. 114 115* ``create_sampler_view`` creates a new sampler view. ``texture`` is associated 116 with the sampler view which results in sampler view holding a reference 117 to the texture. Format specified in template must be compatible 118 with texture format. 119 120* ``sampler_view_destroy`` destroys a sampler view and releases its reference 121 to associated texture. 122 123Shader Resources 124^^^^^^^^^^^^^^^^ 125 126Shader resources are textures or buffers that may be read or written 127from a shader without an associated sampler. This means that they 128have no support for floating point coordinates, address wrap modes or 129filtering. 130 131Shader resources are specified for all the shader stages at once using 132the ``set_shader_resources`` method. When binding texture resources, 133the ``level``, ``first_layer`` and ``last_layer`` pipe_surface fields 134specify the mipmap level and the range of layers the texture will be 135constrained to. In the case of buffers, ``first_element`` and 136``last_element`` specify the range within the buffer that will be used 137by the shader resource. Writes to a shader resource are only allowed 138when the ``writable`` flag is set. 139 140Surfaces 141^^^^^^^^ 142 143These are the means to use resources as color render targets or depthstencil 144attachments. To create one, specify the mip level, the range of layers, and 145the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET). 146Note that layer values are in addition to what is indicated by the geometry 147shader output variable XXX_FIXME (that is if first_layer is 3 and geometry 148shader indicates index 2, the 5th layer of the resource will be used). These 149first_layer and last_layer parameters will only be used for 1d array, 2d array, 150cube, and 3d textures otherwise they are 0. 151 152* ``create_surface`` creates a new surface. 153 154* ``surface_destroy`` destroys a surface and releases its reference to the 155 associated resource. 156 157Stream output targets 158^^^^^^^^^^^^^^^^^^^^^ 159 160Stream output, also known as transform feedback, allows writing the primitives 161produced by the vertex pipeline to buffers. This is done after the geometry 162shader or vertex shader if no geometry shader is present. 163 164The stream output targets are views into buffer resources which can be bound 165as stream outputs and specify a memory range where it's valid to write 166primitives. The pipe driver must implement memory protection such that any 167primitives written outside of the specified memory range are discarded. 168 169Two stream output targets can use the same resource at the same time, but 170with a disjoint memory range. 171 172Additionally, the stream output target internally maintains the offset 173into the buffer which is incremented everytime something is written to it. 174The internal offset is equal to how much data has already been written. 175It can be stored in device memory and the CPU actually doesn't have to query 176it. 177 178The stream output target can be used in a draw command to provide 179the vertex count. The vertex count is derived from the internal offset 180discussed above. 181 182* ``create_stream_output_target`` create a new target. 183 184* ``stream_output_target_destroy`` destroys a target. Users of this should 185 use pipe_so_target_reference instead. 186 187* ``set_stream_output_targets`` binds stream output targets. The parameter 188 append_bitmask is a bitmask, where the i-th bit specifies whether new 189 primitives should be appended to the i-th buffer (writing starts at 190 the internal offset), or whether writing should start at the beginning 191 (the internal offset is effectively set to 0). 192 193NOTE: The currently-bound vertex or geometry shader must be compiled with 194the properly-filled-in structure pipe_stream_output_info describing which 195outputs should be written to buffers and how. The structure is part of 196pipe_shader_state. 197 198Clearing 199^^^^^^^^ 200 201Clear is one of the most difficult concepts to nail down to a single 202interface (due to both different requirements from APIs and also driver/hw 203specific differences). 204 205``clear`` initializes some or all of the surfaces currently bound to 206the framebuffer to particular RGBA, depth, or stencil values. 207Currently, this does not take into account color or stencil write masks (as 208used by GL), and always clears the whole surfaces (no scissoring as used by 209GL clear or explicit rectangles like d3d9 uses). It can, however, also clear 210only depth or stencil in a combined depth/stencil surface, if the driver 211supports PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE. 212If a surface includes several layers then all layers will be cleared. 213 214``clear_render_target`` clears a single color rendertarget with the specified 215color value. While it is only possible to clear one surface at a time (which can 216include several layers), this surface need not be bound to the framebuffer. 217 218``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface 219with the specified depth and stencil values (for combined depth/stencil buffers, 220is is also possible to only clear one or the other part). While it is only 221possible to clear one surface at a time (which can include several layers), 222this surface need not be bound to the framebuffer. 223 224 225Drawing 226^^^^^^^ 227 228``draw_vbo`` draws a specified primitive. The primitive mode and other 229properties are described by ``pipe_draw_info``. 230 231The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the 232the mode of the primitive and the vertices to be fetched, in the range between 233``start`` to ``start``+``count``-1, inclusive. 234 235Every instance with instanceID in the range between ``start_instance`` and 236``start_instance``+``instance_count``-1, inclusive, will be drawn. 237 238If there is an index buffer bound, and ``indexed`` field is true, all vertex 239indices will be looked up in the index buffer. 240 241In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower 242and upper bound of the indices contained in the index buffer inside the range 243between ``start`` to ``start``+``count``-1. This allows the driver to 244determine which subset of vertices will be referenced during te draw call 245without having to scan the index buffer. Providing a over-estimation of the 246the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and 2470xffffffff respectively, must give exactly the same rendering, albeit with less 248performance due to unreferenced vertex buffers being unnecessarily DMA'ed or 249processed. Providing a underestimation of the true bounds will result in 250undefined behavior, but should not result in program or system failure. 251 252In case of non-indexed draw, ``min_index`` should be set to 253``start`` and ``max_index`` should be set to ``start``+``count``-1. 254 255``index_bias`` is a value added to every vertex index after lookup and before 256fetching vertex attributes. 257 258When drawing indexed primitives, the primitive restart index can be 259used to draw disjoint primitive strips. For example, several separate 260line strips can be drawn by designating a special index value as the 261restart index. The ``primitive_restart`` flag enables/disables this 262feature. The ``restart_index`` field specifies the restart index value. 263 264When primitive restart is in use, array indexes are compared to the 265restart index before adding the index_bias offset. 266 267If a given vertex element has ``instance_divisor`` set to 0, it is said 268it contains per-vertex data and effective vertex attribute address needs 269to be recalculated for every index. 270 271 attribAddr = ``stride`` * index + ``src_offset`` 272 273If a given vertex element has ``instance_divisor`` set to non-zero, 274it is said it contains per-instance data and effective vertex attribute 275address needs to recalculated for every ``instance_divisor``-th instance. 276 277 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset`` 278 279In the above formulas, ``src_offset`` is taken from the given vertex element 280and ``stride`` is taken from a vertex buffer associated with the given 281vertex element. 282 283The calculated attribAddr is used as an offset into the vertex buffer to 284fetch the attribute data. 285 286The value of ``instanceID`` can be read in a vertex shader through a system 287value register declared with INSTANCEID semantic name. 288 289 290Queries 291^^^^^^^ 292 293Queries gather some statistic from the 3D pipeline over one or more 294draws. Queries may be nested, though only d3d1x currently exercises this. 295 296Queries can be created with ``create_query`` and deleted with 297``destroy_query``. To start a query, use ``begin_query``, and when finished, 298use ``end_query`` to end the query. 299 300``get_query_result`` is used to retrieve the results of a query. If 301the ``wait`` parameter is TRUE, then the ``get_query_result`` call 302will block until the results of the query are ready (and TRUE will be 303returned). Otherwise, if the ``wait`` parameter is FALSE, the call 304will not block and the return value will be TRUE if the query has 305completed or FALSE otherwise. 306 307The interface currently includes the following types of queries: 308 309``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which 310are written to the framebuffer without being culled by 311:ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions. 312The result is an unsigned 64-bit integer. 313This query can be used with ``render_condition``. 314 315In cases where a boolean result of an occlusion query is enough, 316``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like 317``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean 318value of FALSE for cases where COUNTER would result in 0 and TRUE 319for all other cases. 320This query can be used with ``render_condition``. 321 322``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds, 323the context takes to perform operations. 324The result is an unsigned 64-bit integer. 325 326``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp, 327scaled to nanoseconds, recorded after all commands issued prior to 328``end_query`` have been processed. 329This query does not require a call to ``begin_query``. 330The result is an unsigned 64-bit integer. 331 332``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check whether the 333internal timer resolution is good enough to distinguish between the 334events at ``begin_query`` and ``end_query``. 335The result is a 64-bit integer specifying the timer resolution in Hz, 336followed by a boolean value indicating whether the timer has incremented. 337 338``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating 339the number of primitives processed by the pipeline. 340 341``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating 342the number of primitives written to stream output buffers. 343 344``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to 345the results of 346``PIPE_QUERY_PRIMITIVES_EMITTED`` and 347``PIPE_QUERY_PRIMITIVES_GENERATED``, in this order. 348 349``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating 350whether the stream output targets have overflowed as a result of the 351commands issued between ``begin_query`` and ``end_query``. 352This query can be used with ``render_condition``. 353 354``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether 355all commands issued before ``end_query`` have completed. However, this 356does not imply serialization. 357This query does not require a call to ``begin_query``. 358 359``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following 36064-bit integers: 361Number of vertices read from vertex buffers. 362Number of primitives read from vertex buffers. 363Number of vertex shader threads launched. 364Number of geometry shader threads launched. 365Number of primitives generated by geometry shaders. 366Number of primitives forwarded to the rasterizer. 367Number of primitives rasterized. 368Number of fragment shader threads launched. 369Number of tessellation control shader threads launched. 370Number of tessellation evaluation shader threads launched. 371If a shader type is not supported by the device/driver, 372the corresponding values should be set to 0. 373 374Gallium does not guarantee the availability of any query types; one must 375always check the capabilities of the :ref:`Screen` first. 376 377 378Conditional Rendering 379^^^^^^^^^^^^^^^^^^^^^ 380 381A drawing command can be skipped depending on the outcome of a query 382(typically an occlusion query). The ``render_condition`` function specifies 383the query which should be checked prior to rendering anything. 384 385If ``render_condition`` is called with ``query`` = NULL, conditional 386rendering is disabled and drawing takes place normally. 387 388If ``render_condition`` is called with a non-null ``query`` subsequent 389drawing commands will be predicated on the outcome of the query. If 390the query result is zero subsequent drawing commands will be skipped. 391 392If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the 393query to complete before deciding whether to render. 394 395If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet 396completed, the drawing command will be executed normally. If the query 397has completed, drawing will be predicated on the outcome of the query. 398 399If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or 400PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above 401for the non-REGION modes but in the case that an occulusion query returns 402a non-zero result, regions which were occluded may be ommitted by subsequent 403drawing commands. This can result in better performance with some GPUs. 404Normally, if the occlusion query returned a non-zero result subsequent 405drawing happens normally so fragments may be generated, shaded and 406processed even where they're known to be obscured. 407 408 409Flushing 410^^^^^^^^ 411 412``flush`` 413 414 415Resource Busy Queries 416^^^^^^^^^^^^^^^^^^^^^ 417 418``is_resource_referenced`` 419 420 421 422Blitting 423^^^^^^^^ 424 425These methods emulate classic blitter controls. 426 427These methods operate directly on ``pipe_resource`` objects, and stand 428apart from any 3D state in the context. Blitting functionality may be 429moved to a separate abstraction at some point in the future. 430 431``resource_copy_region`` blits a region of a resource to a region of another 432resource, provided that both resources have the same format, or compatible 433formats, i.e., formats for which copying the bytes from the source resource 434unmodified to the destination resource will achieve the same effect of a 435textured quad blitter.. The source and destination may be the same resource, 436but overlapping blits are not permitted. 437 438``resource_resolve`` resolves a multisampled resource into a non-multisampled 439one. Their formats must match. This function must be present if a driver 440supports multisampling. 441The region that is to be resolved is described by ``pipe_resolve_info``, which 442provides a source and a destination rectangle. 443The source rectangle may be vertically flipped, but otherwise the dimensions 444of the rectangles must match, unless PIPE_CAP_SCALED_RESOLVE is supported, 445in which case scaling and horizontal flipping are allowed as well. 446The result of resolving depth/stencil values may be any function of the values at 447the sample points, but returning the value of the centermost sample is preferred. 448 449The interfaces to these calls are likely to change to make it easier 450for a driver to batch multiple blits with the same source and 451destination. 452 453Transfers 454^^^^^^^^^ 455 456These methods are used to get data to/from a resource. 457 458``get_transfer`` creates a transfer object. 459 460``transfer_destroy`` destroys the transfer object. May cause 461data to be written to the resource at this point. 462 463``transfer_map`` creates a memory mapping for the transfer object. 464The returned map points to the start of the mapped range according to 465the box region, not the beginning of the resource. 466 467``transfer_unmap`` remove the memory mapping for the transfer object. 468Any pointers into the map should be considered invalid and discarded. 469 470``transfer_inline_write`` performs a simplified transfer for simple writes. 471Basically get_transfer, transfer_map, data write, transfer_unmap, and 472transfer_destroy all in one. 473 474 475The box parameter to some of these functions defines a 1D, 2D or 3D 476region of pixels. This is self-explanatory for 1D, 2D and 3D texture 477targets. 478 479For PIPE_TEXTURE_1D_ARRAY, the box::y and box::height fields refer to the 480array dimension of the texture. 481 482For PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth fields refer to the 483array dimension of the texture. 484 485For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the 486faces of the cube map (z + depth <= 6). 487 488 489 490.. _transfer_flush_region: 491 492transfer_flush_region 493%%%%%%%%%%%%%%%%%%%%% 494 495If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically 496be flushed on write or unmap. Flushes must be requested with 497``transfer_flush_region``. Flush ranges are relative to the mapped range, not 498the beginning of the resource. 499 500 501 502.. _texture_barrier 503 504texture_barrier 505%%%%%%%%%%%%%%% 506 507This function flushes all pending writes to the currently-set surfaces and 508invalidates all read caches of the currently-set samplers. 509 510 511 512.. _pipe_transfer: 513 514PIPE_TRANSFER 515^^^^^^^^^^^^^ 516 517These flags control the behavior of a transfer object. 518 519``PIPE_TRANSFER_READ`` 520 Resource contents read back (or accessed directly) at transfer create time. 521 522``PIPE_TRANSFER_WRITE`` 523 Resource contents will be written back at transfer_destroy time (or modified 524 as a result of being accessed directly). 525 526``PIPE_TRANSFER_MAP_DIRECTLY`` 527 a transfer should directly map the resource. May return NULL if not supported. 528 529``PIPE_TRANSFER_DISCARD_RANGE`` 530 The memory within the mapped region is discarded. Cannot be used with 531 ``PIPE_TRANSFER_READ``. 532 533``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE`` 534 Discards all memory backing the resource. It should not be used with 535 ``PIPE_TRANSFER_READ``. 536 537``PIPE_TRANSFER_DONTBLOCK`` 538 Fail if the resource cannot be mapped immediately. 539 540``PIPE_TRANSFER_UNSYNCHRONIZED`` 541 Do not synchronize pending operations on the resource when mapping. The 542 interaction of any writes to the map and any operations pending on the 543 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``. 544 545``PIPE_TRANSFER_FLUSH_EXPLICIT`` 546 Written ranges will be notified later with :ref:`transfer_flush_region`. 547 Cannot be used with ``PIPE_TRANSFER_READ``. 548 549 550Compute kernel execution 551^^^^^^^^^^^^^^^^^^^^^^^^ 552 553A compute program can be defined, bound or destroyed using 554``create_compute_state``, ``bind_compute_state`` or 555``destroy_compute_state`` respectively. 556 557Any of the subroutines contained within the compute program can be 558executed on the device using the ``launch_grid`` method. This method 559will execute as many instances of the program as elements in the 560specified N-dimensional grid, hopefully in parallel. 561 562The compute program has access to four special resources: 563 564* ``GLOBAL`` represents a memory space shared among all the threads 565 running on the device. An arbitrary buffer created with the 566 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the 567 ``set_global_binding`` method. 568 569* ``LOCAL`` represents a memory space shared among all the threads 570 running in the same working group. The initial contents of this 571 resource are undefined. 572 573* ``PRIVATE`` represents a memory space local to a single thread. 574 The initial contents of this resource are undefined. 575 576* ``INPUT`` represents a read-only memory space that can be 577 initialized at ``launch_grid`` time. 578 579These resources use a byte-based addressing scheme, and they can be 580accessed from the compute program by means of the LOAD/STORE TGSI 581opcodes. Additional resources to be accessed using the same opcodes 582may be specified by the user with the ``set_compute_resources`` 583method. 584 585In addition, normal texture sampling is allowed from the compute 586program: ``bind_compute_sampler_states`` may be used to set up texture 587samplers for the compute stage and ``set_compute_sampler_views`` may 588be used to bind a number of sampler views to it. 589