1 .. _context: 2 3 Context 4 ======= 5 6 A Gallium rendering context encapsulates the state which effects 3D 7 rendering such as blend state, depth/stencil state, texture samplers, 8 etc. 9 10 Note that resource/texture allocation is not per-context but per-screen. 11 12 13 Methods 14 ------- 15 16 CSO State 17 ^^^^^^^^^ 18 19 All Constant State Object (CSO) state is created, bound, and destroyed, 20 with triplets of methods that all follow a specific naming scheme. 21 For example, ``create_blend_state``, ``bind_blend_state``, and 22 ``destroy_blend_state``. 23 24 CSO 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 40 Resource Binding State 41 ^^^^^^^^^^^^^^^^^^^^^^ 42 43 This state describes how resources in various flavours (textures, 44 buffers, 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 52 * ``set_framebuffer_state`` 53 54 * ``set_vertex_buffers`` 55 56 * ``set_index_buffer`` 57 58 59 Non-CSO State 60 ^^^^^^^^^^^^^ 61 62 These pieces of state are too small, variable, and/or trivial to have CSO 63 objects. They all follow simple, one-method binding calls, e.g. 64 ``set_blend_color``. 65 66 * ``set_stencil_ref`` sets the stencil front and back reference values 67 which are used as comparison values in stencil test. 68 * ``set_blend_color`` 69 * ``set_sample_mask`` 70 * ``set_min_samples`` sets the minimum number of samples that must be run. 71 * ``set_clip_state`` 72 * ``set_polygon_stipple`` 73 * ``set_scissor_states`` sets the bounds for the scissor test, which culls 74 pixels before blending to render targets. If the :ref:`Rasterizer` does 75 not have the scissor test enabled, then the scissor bounds never need to 76 be set since they will not be used. Note that scissor xmin and ymin are 77 inclusive, but xmax and ymax are exclusive. The inclusive ranges in x 78 and y would be [xmin..xmax-1] and [ymin..ymax-1]. The number of scissors 79 should be the same as the number of set viewports and can be up to 80 PIPE_MAX_VIEWPORTS. 81 * ``set_viewport_states`` 82 * ``set_window_rectangles`` sets the window rectangles to be used for 83 rendering, as defined by GL_EXT_window_rectangles. There are two 84 modes - include and exclude, which define whether the supplied 85 rectangles are to be used for including fragments or excluding 86 them. All of the rectangles are ORed together, so in exclude mode, 87 any fragment inside any rectangle would be culled, while in include 88 mode, any fragment outside all rectangles would be culled. xmin/ymin 89 are inclusive, while xmax/ymax are exclusive (same as scissor states 90 above). Note that this only applies to draws, not clears or 91 blits. (Blits have their own way to pass the requisite rectangles 92 in.) 93 * ``set_tess_state`` configures the default tessellation parameters: 94 * ``default_outer_level`` is the default value for the outer tessellation 95 levels. This corresponds to GL's ``PATCH_DEFAULT_OUTER_LEVEL``. 96 * ``default_inner_level`` is the default value for the inner tessellation 97 levels. This corresponds to GL's ``PATCH_DEFAULT_INNER_LEVEL``. 98 * ``set_debug_callback`` sets the callback to be used for reporting 99 various debug messages, eventually reported via KHR_debug and 100 similar mechanisms. 101 102 103 Sampler Views 104 ^^^^^^^^^^^^^ 105 106 These are the means to bind textures to shader stages. To create one, specify 107 its format, swizzle and LOD range in sampler view template. 108 109 If texture format is different than template format, it is said the texture 110 is being cast to another format. Casting can be done only between compatible 111 formats, that is formats that have matching component order and sizes. 112 113 Swizzle fields specify they way in which fetched texel components are placed 114 in the result register. For example, ``swizzle_r`` specifies what is going to be 115 placed in first component of result register. 116 117 The ``first_level`` and ``last_level`` fields of sampler view template specify 118 the LOD range the texture is going to be constrained to. Note that these 119 values are in addition to the respective min_lod, max_lod values in the 120 pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip 121 level used for sampling from the resource is effectively the fifth). 122 123 The ``first_layer`` and ``last_layer`` fields specify the layer range the 124 texture is going to be constrained to. Similar to the LOD range, this is added 125 to the array index which is used for sampling. 126 127 * ``set_sampler_views`` binds an array of sampler views to a shader stage. 128 Every binding point acquires a reference 129 to a respective sampler view and releases a reference to the previous 130 sampler view. 131 132 * ``create_sampler_view`` creates a new sampler view. ``texture`` is associated 133 with the sampler view which results in sampler view holding a reference 134 to the texture. Format specified in template must be compatible 135 with texture format. 136 137 * ``sampler_view_destroy`` destroys a sampler view and releases its reference 138 to associated texture. 139 140 Shader Resources 141 ^^^^^^^^^^^^^^^^ 142 143 Shader resources are textures or buffers that may be read or written 144 from a shader without an associated sampler. This means that they 145 have no support for floating point coordinates, address wrap modes or 146 filtering. 147 148 There are 2 types of shader resources: buffers and images. 149 150 Buffers are specified using the ``set_shader_buffers`` method. 151 152 Images are specified using the ``set_shader_images`` method. When binding 153 images, the ``level``, ``first_layer`` and ``last_layer`` pipe_image_view 154 fields specify the mipmap level and the range of layers the image will be 155 constrained to. 156 157 Surfaces 158 ^^^^^^^^ 159 160 These are the means to use resources as color render targets or depthstencil 161 attachments. To create one, specify the mip level, the range of layers, and 162 the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET). 163 Note that layer values are in addition to what is indicated by the geometry 164 shader output variable XXX_FIXME (that is if first_layer is 3 and geometry 165 shader indicates index 2, the 5th layer of the resource will be used). These 166 first_layer and last_layer parameters will only be used for 1d array, 2d array, 167 cube, and 3d textures otherwise they are 0. 168 169 * ``create_surface`` creates a new surface. 170 171 * ``surface_destroy`` destroys a surface and releases its reference to the 172 associated resource. 173 174 Stream output targets 175 ^^^^^^^^^^^^^^^^^^^^^ 176 177 Stream output, also known as transform feedback, allows writing the primitives 178 produced by the vertex pipeline to buffers. This is done after the geometry 179 shader or vertex shader if no geometry shader is present. 180 181 The stream output targets are views into buffer resources which can be bound 182 as stream outputs and specify a memory range where it's valid to write 183 primitives. The pipe driver must implement memory protection such that any 184 primitives written outside of the specified memory range are discarded. 185 186 Two stream output targets can use the same resource at the same time, but 187 with a disjoint memory range. 188 189 Additionally, the stream output target internally maintains the offset 190 into the buffer which is incremented everytime something is written to it. 191 The internal offset is equal to how much data has already been written. 192 It can be stored in device memory and the CPU actually doesn't have to query 193 it. 194 195 The stream output target can be used in a draw command to provide 196 the vertex count. The vertex count is derived from the internal offset 197 discussed above. 198 199 * ``create_stream_output_target`` create a new target. 200 201 * ``stream_output_target_destroy`` destroys a target. Users of this should 202 use pipe_so_target_reference instead. 203 204 * ``set_stream_output_targets`` binds stream output targets. The parameter 205 offset is an array which specifies the internal offset of the buffer. The 206 internal offset is, besides writing, used for reading the data during the 207 draw_auto stage, i.e. it specifies how much data there is in the buffer 208 for the purposes of the draw_auto stage. -1 means the buffer should 209 be appended to, and everything else sets the internal offset. 210 211 NOTE: The currently-bound vertex or geometry shader must be compiled with 212 the properly-filled-in structure pipe_stream_output_info describing which 213 outputs should be written to buffers and how. The structure is part of 214 pipe_shader_state. 215 216 Clearing 217 ^^^^^^^^ 218 219 Clear is one of the most difficult concepts to nail down to a single 220 interface (due to both different requirements from APIs and also driver/hw 221 specific differences). 222 223 ``clear`` initializes some or all of the surfaces currently bound to 224 the framebuffer to particular RGBA, depth, or stencil values. 225 Currently, this does not take into account color or stencil write masks (as 226 used by GL), and always clears the whole surfaces (no scissoring as used by 227 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear 228 only depth or stencil in a combined depth/stencil surface. 229 If a surface includes several layers then all layers will be cleared. 230 231 ``clear_render_target`` clears a single color rendertarget with the specified 232 color value. While it is only possible to clear one surface at a time (which can 233 include several layers), this surface need not be bound to the framebuffer. 234 If render_condition_enabled is false, any current rendering condition is ignored 235 and the clear will be unconditional. 236 237 ``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface 238 with the specified depth and stencil values (for combined depth/stencil buffers, 239 it is also possible to only clear one or the other part). While it is only 240 possible to clear one surface at a time (which can include several layers), 241 this surface need not be bound to the framebuffer. 242 If render_condition_enabled is false, any current rendering condition is ignored 243 and the clear will be unconditional. 244 245 ``clear_texture`` clears a non-PIPE_BUFFER resource's specified level 246 and bounding box with a clear value provided in that resource's native 247 format. 248 249 ``clear_buffer`` clears a PIPE_BUFFER resource with the specified clear value 250 (which may be multiple bytes in length). Logically this is a memset with a 251 multi-byte element value starting at offset bytes from resource start, going 252 for size bytes. It is guaranteed that size % clear_value_size == 0. 253 254 255 Drawing 256 ^^^^^^^ 257 258 ``draw_vbo`` draws a specified primitive. The primitive mode and other 259 properties are described by ``pipe_draw_info``. 260 261 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the 262 the mode of the primitive and the vertices to be fetched, in the range between 263 ``start`` to ``start``+``count``-1, inclusive. 264 265 Every instance with instanceID in the range between ``start_instance`` and 266 ``start_instance``+``instance_count``-1, inclusive, will be drawn. 267 268 If there is an index buffer bound, and ``indexed`` field is true, all vertex 269 indices will be looked up in the index buffer. 270 271 In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower 272 and upper bound of the indices contained in the index buffer inside the range 273 between ``start`` to ``start``+``count``-1. This allows the driver to 274 determine which subset of vertices will be referenced during te draw call 275 without having to scan the index buffer. Providing a over-estimation of the 276 the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and 277 0xffffffff respectively, must give exactly the same rendering, albeit with less 278 performance due to unreferenced vertex buffers being unnecessarily DMA'ed or 279 processed. Providing a underestimation of the true bounds will result in 280 undefined behavior, but should not result in program or system failure. 281 282 In case of non-indexed draw, ``min_index`` should be set to 283 ``start`` and ``max_index`` should be set to ``start``+``count``-1. 284 285 ``index_bias`` is a value added to every vertex index after lookup and before 286 fetching vertex attributes. 287 288 When drawing indexed primitives, the primitive restart index can be 289 used to draw disjoint primitive strips. For example, several separate 290 line strips can be drawn by designating a special index value as the 291 restart index. The ``primitive_restart`` flag enables/disables this 292 feature. The ``restart_index`` field specifies the restart index value. 293 294 When primitive restart is in use, array indexes are compared to the 295 restart index before adding the index_bias offset. 296 297 If a given vertex element has ``instance_divisor`` set to 0, it is said 298 it contains per-vertex data and effective vertex attribute address needs 299 to be recalculated for every index. 300 301 attribAddr = ``stride`` * index + ``src_offset`` 302 303 If a given vertex element has ``instance_divisor`` set to non-zero, 304 it is said it contains per-instance data and effective vertex attribute 305 address needs to recalculated for every ``instance_divisor``-th instance. 306 307 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset`` 308 309 In the above formulas, ``src_offset`` is taken from the given vertex element 310 and ``stride`` is taken from a vertex buffer associated with the given 311 vertex element. 312 313 The calculated attribAddr is used as an offset into the vertex buffer to 314 fetch the attribute data. 315 316 The value of ``instanceID`` can be read in a vertex shader through a system 317 value register declared with INSTANCEID semantic name. 318 319 320 Queries 321 ^^^^^^^ 322 323 Queries gather some statistic from the 3D pipeline over one or more 324 draws. Queries may be nested, though not all state trackers exercise this. 325 326 Queries can be created with ``create_query`` and deleted with 327 ``destroy_query``. To start a query, use ``begin_query``, and when finished, 328 use ``end_query`` to end the query. 329 330 ``create_query`` takes a query type (``PIPE_QUERY_*``), as well as an index, 331 which is the vertex stream for ``PIPE_QUERY_PRIMITIVES_GENERATED`` and 332 ``PIPE_QUERY_PRIMITIVES_EMITTED``, and allocates a query structure. 333 334 ``begin_query`` will clear/reset previous query results. 335 336 ``get_query_result`` is used to retrieve the results of a query. If 337 the ``wait`` parameter is TRUE, then the ``get_query_result`` call 338 will block until the results of the query are ready (and TRUE will be 339 returned). Otherwise, if the ``wait`` parameter is FALSE, the call 340 will not block and the return value will be TRUE if the query has 341 completed or FALSE otherwise. 342 343 ``get_query_result_resource`` is used to store the result of a query into 344 a resource without synchronizing with the CPU. This write will optionally 345 wait for the query to complete, and will optionally write whether the value 346 is available instead of the value itself. 347 348 ``set_active_query_state`` Set whether all current non-driver queries except 349 TIME_ELAPSED are active or paused. 350 351 The interface currently includes the following types of queries: 352 353 ``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which 354 are written to the framebuffer without being culled by 355 :ref:`depth-stencil-alpha` testing or shader KILL instructions. 356 The result is an unsigned 64-bit integer. 357 This query can be used with ``render_condition``. 358 359 In cases where a boolean result of an occlusion query is enough, 360 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like 361 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean 362 value of FALSE for cases where COUNTER would result in 0 and TRUE 363 for all other cases. 364 This query can be used with ``render_condition``. 365 366 ``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds, 367 the context takes to perform operations. 368 The result is an unsigned 64-bit integer. 369 370 ``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp, 371 scaled to nanoseconds, recorded after all commands issued prior to 372 ``end_query`` have been processed. 373 This query does not require a call to ``begin_query``. 374 The result is an unsigned 64-bit integer. 375 376 ``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check the 377 internal timer resolution and whether the timestamp counter has become 378 unreliable due to things like throttling etc. - only if this is FALSE 379 a timestamp query (within the timestamp_disjoint query) should be trusted. 380 The result is a 64-bit integer specifying the timer resolution in Hz, 381 followed by a boolean value indicating whether the timestamp counter 382 is discontinuous or disjoint. 383 384 ``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating 385 the number of primitives processed by the pipeline (regardless of whether 386 stream output is active or not). 387 388 ``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating 389 the number of primitives written to stream output buffers. 390 391 ``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to 392 the result of 393 ``PIPE_QUERY_PRIMITIVES_EMITTED`` and 394 the number of primitives that would have been written to stream output buffers 395 if they had infinite space available (primitives_storage_needed), in this order. 396 XXX the 2nd value is equivalent to ``PIPE_QUERY_PRIMITIVES_GENERATED`` but it is 397 unclear if it should be increased if stream output is not active. 398 399 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating 400 whether the stream output targets have overflowed as a result of the 401 commands issued between ``begin_query`` and ``end_query``. 402 This query can be used with ``render_condition``. 403 404 ``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether 405 all commands issued before ``end_query`` have completed. However, this 406 does not imply serialization. 407 This query does not require a call to ``begin_query``. 408 409 ``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following 410 64-bit integers: 411 Number of vertices read from vertex buffers. 412 Number of primitives read from vertex buffers. 413 Number of vertex shader threads launched. 414 Number of geometry shader threads launched. 415 Number of primitives generated by geometry shaders. 416 Number of primitives forwarded to the rasterizer. 417 Number of primitives rasterized. 418 Number of fragment shader threads launched. 419 Number of tessellation control shader threads launched. 420 Number of tessellation evaluation shader threads launched. 421 If a shader type is not supported by the device/driver, 422 the corresponding values should be set to 0. 423 424 Gallium does not guarantee the availability of any query types; one must 425 always check the capabilities of the :ref:`Screen` first. 426 427 428 Conditional Rendering 429 ^^^^^^^^^^^^^^^^^^^^^ 430 431 A drawing command can be skipped depending on the outcome of a query 432 (typically an occlusion query, or streamout overflow predicate). 433 The ``render_condition`` function specifies the query which should be checked 434 prior to rendering anything. Functions always honoring render_condition include 435 (and are limited to) draw_vbo and clear. 436 The blit, clear_render_target and clear_depth_stencil functions (but 437 not resource_copy_region, which seems inconsistent) can also optionally honor 438 the current render condition. 439 440 If ``render_condition`` is called with ``query`` = NULL, conditional 441 rendering is disabled and drawing takes place normally. 442 443 If ``render_condition`` is called with a non-null ``query`` subsequent 444 drawing commands will be predicated on the outcome of the query. 445 Commands will be skipped if ``condition`` is equal to the predicate result 446 (for non-boolean queries such as OCCLUSION_QUERY, zero counts as FALSE, 447 non-zero as TRUE). 448 449 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the 450 query to complete before deciding whether to render. 451 452 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet 453 completed, the drawing command will be executed normally. If the query 454 has completed, drawing will be predicated on the outcome of the query. 455 456 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or 457 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above 458 for the non-REGION modes but in the case that an occlusion query returns 459 a non-zero result, regions which were occluded may be ommitted by subsequent 460 drawing commands. This can result in better performance with some GPUs. 461 Normally, if the occlusion query returned a non-zero result subsequent 462 drawing happens normally so fragments may be generated, shaded and 463 processed even where they're known to be obscured. 464 465 466 Flushing 467 ^^^^^^^^ 468 469 ``flush`` 470 471 PIPE_FLUSH_END_OF_FRAME: Whether the flush marks the end of frame. 472 473 PIPE_FLUSH_DEFERRED: It is not required to flush right away, but it is required 474 to return a valid fence. If fence_finish is called with the returned fence 475 and the context is still unflushed, and the ctx parameter of fence_finish is 476 equal to the context where the fence was created, fence_finish will flush 477 the context. 478 479 480 ``flush_resource`` 481 482 Flush the resource cache, so that the resource can be used 483 by an external client. Possible usage: 484 - flushing a resource before presenting it on the screen 485 - flushing a resource if some other process or device wants to use it 486 This shouldn't be used to flush caches if the resource is only managed 487 by a single pipe_screen and is not shared with another process. 488 (i.e. you shouldn't use it to flush caches explicitly if you want to e.g. 489 use the resource for texturing) 490 491 492 493 Resource Busy Queries 494 ^^^^^^^^^^^^^^^^^^^^^ 495 496 ``is_resource_referenced`` 497 498 499 500 Blitting 501 ^^^^^^^^ 502 503 These methods emulate classic blitter controls. 504 505 These methods operate directly on ``pipe_resource`` objects, and stand 506 apart from any 3D state in the context. Blitting functionality may be 507 moved to a separate abstraction at some point in the future. 508 509 ``resource_copy_region`` blits a region of a resource to a region of another 510 resource, provided that both resources have the same format, or compatible 511 formats, i.e., formats for which copying the bytes from the source resource 512 unmodified to the destination resource will achieve the same effect of a 513 textured quad blitter.. The source and destination may be the same resource, 514 but overlapping blits are not permitted. 515 This can be considered the equivalent of a CPU memcpy. 516 517 ``blit`` blits a region of a resource to a region of another resource, including 518 scaling, format conversion, and up-/downsampling, as well as a destination clip 519 rectangle (scissors) and window rectangles. It can also optionally honor the 520 current render condition (but either way the blit itself never contributes 521 anything to queries currently gathering data). 522 As opposed to manually drawing a textured quad, this lets the pipe driver choose 523 the optimal method for blitting (like using a special 2D engine), and usually 524 offers, for example, accelerated stencil-only copies even where 525 PIPE_CAP_SHADER_STENCIL_EXPORT is not available. 526 527 528 Transfers 529 ^^^^^^^^^ 530 531 These methods are used to get data to/from a resource. 532 533 ``transfer_map`` creates a memory mapping and the transfer object 534 associated with it. 535 The returned pointer points to the start of the mapped range according to 536 the box region, not the beginning of the resource. If transfer_map fails, 537 the returned pointer to the buffer memory is NULL, and the pointer 538 to the transfer object remains unchanged (i.e. it can be non-NULL). 539 540 ``transfer_unmap`` remove the memory mapping for and destroy 541 the transfer object. The pointer into the resource should be considered 542 invalid and discarded. 543 544 ``texture_subdata`` and ``buffer_subdata`` perform a simplified 545 transfer for simple writes. Basically transfer_map, data write, and 546 transfer_unmap all in one. 547 548 549 The box parameter to some of these functions defines a 1D, 2D or 3D 550 region of pixels. This is self-explanatory for 1D, 2D and 3D texture 551 targets. 552 553 For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth 554 fields refer to the array dimension of the texture. 555 556 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the 557 faces of the cube map (z + depth <= 6). 558 559 For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both 560 the face and array dimension of the texture (face = z % 6, array = z / 6). 561 562 563 .. _transfer_flush_region: 564 565 transfer_flush_region 566 %%%%%%%%%%%%%%%%%%%%% 567 568 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically 569 be flushed on write or unmap. Flushes must be requested with 570 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not 571 the beginning of the resource. 572 573 574 575 .. _texture_barrier: 576 577 texture_barrier 578 %%%%%%%%%%%%%%% 579 580 This function flushes all pending writes to the currently-set surfaces and 581 invalidates all read caches of the currently-set samplers. This can be used 582 for both regular textures as well as for framebuffers read via FBFETCH. 583 584 585 586 .. _memory_barrier: 587 588 memory_barrier 589 %%%%%%%%%%%%%%% 590 591 This function flushes caches according to which of the PIPE_BARRIER_* flags 592 are set. 593 594 595 596 .. _pipe_transfer: 597 598 PIPE_TRANSFER 599 ^^^^^^^^^^^^^ 600 601 These flags control the behavior of a transfer object. 602 603 ``PIPE_TRANSFER_READ`` 604 Resource contents read back (or accessed directly) at transfer create time. 605 606 ``PIPE_TRANSFER_WRITE`` 607 Resource contents will be written back at transfer_unmap time (or modified 608 as a result of being accessed directly). 609 610 ``PIPE_TRANSFER_MAP_DIRECTLY`` 611 a transfer should directly map the resource. May return NULL if not supported. 612 613 ``PIPE_TRANSFER_DISCARD_RANGE`` 614 The memory within the mapped region is discarded. Cannot be used with 615 ``PIPE_TRANSFER_READ``. 616 617 ``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE`` 618 Discards all memory backing the resource. It should not be used with 619 ``PIPE_TRANSFER_READ``. 620 621 ``PIPE_TRANSFER_DONTBLOCK`` 622 Fail if the resource cannot be mapped immediately. 623 624 ``PIPE_TRANSFER_UNSYNCHRONIZED`` 625 Do not synchronize pending operations on the resource when mapping. The 626 interaction of any writes to the map and any operations pending on the 627 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``. 628 629 ``PIPE_TRANSFER_FLUSH_EXPLICIT`` 630 Written ranges will be notified later with :ref:`transfer_flush_region`. 631 Cannot be used with ``PIPE_TRANSFER_READ``. 632 633 ``PIPE_TRANSFER_PERSISTENT`` 634 Allows the resource to be used for rendering while mapped. 635 PIPE_RESOURCE_FLAG_MAP_PERSISTENT must be set when creating 636 the resource. 637 If COHERENT is not set, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER) 638 must be called to ensure the device can see what the CPU has written. 639 640 ``PIPE_TRANSFER_COHERENT`` 641 If PERSISTENT is set, this ensures any writes done by the device are 642 immediately visible to the CPU and vice versa. 643 PIPE_RESOURCE_FLAG_MAP_COHERENT must be set when creating 644 the resource. 645 646 Compute kernel execution 647 ^^^^^^^^^^^^^^^^^^^^^^^^ 648 649 A compute program can be defined, bound or destroyed using 650 ``create_compute_state``, ``bind_compute_state`` or 651 ``destroy_compute_state`` respectively. 652 653 Any of the subroutines contained within the compute program can be 654 executed on the device using the ``launch_grid`` method. This method 655 will execute as many instances of the program as elements in the 656 specified N-dimensional grid, hopefully in parallel. 657 658 The compute program has access to four special resources: 659 660 * ``GLOBAL`` represents a memory space shared among all the threads 661 running on the device. An arbitrary buffer created with the 662 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the 663 ``set_global_binding`` method. 664 665 * ``LOCAL`` represents a memory space shared among all the threads 666 running in the same working group. The initial contents of this 667 resource are undefined. 668 669 * ``PRIVATE`` represents a memory space local to a single thread. 670 The initial contents of this resource are undefined. 671 672 * ``INPUT`` represents a read-only memory space that can be 673 initialized at ``launch_grid`` time. 674 675 These resources use a byte-based addressing scheme, and they can be 676 accessed from the compute program by means of the LOAD/STORE TGSI 677 opcodes. Additional resources to be accessed using the same opcodes 678 may be specified by the user with the ``set_compute_resources`` 679 method. 680 681 In addition, normal texture sampling is allowed from the compute 682 program: ``bind_sampler_states`` may be used to set up texture 683 samplers for the compute stage and ``set_sampler_views`` may 684 be used to bind a number of sampler views to it. 685 686 Mipmap generation 687 ^^^^^^^^^^^^^^^^^ 688 689 If PIPE_CAP_GENERATE_MIPMAP is true, ``generate_mipmap`` can be used 690 to generate mipmaps for the specified texture resource. 691 It replaces texel image levels base_level+1 through 692 last_level for layers range from first_layer through last_layer. 693 It returns TRUE if mipmap generation succeeds, otherwise it 694 returns FALSE. Mipmap generation may fail when it is not supported 695 for particular texture types or formats. 696 697 Device resets 698 ^^^^^^^^^^^^^ 699 700 The state tracker can query or request notifications of when the GPU 701 is reset for whatever reason (application error, driver error). When 702 a GPU reset happens, the context becomes unusable and all related state 703 should be considered lost and undefined. Despite that, context 704 notifications are single-shot, i.e. subsequent calls to 705 ``get_device_reset_status`` will return PIPE_NO_RESET. 706 707 * ``get_device_reset_status`` queries whether a device reset has happened 708 since the last call or since the last notification by callback. 709 * ``set_device_reset_callback`` sets a callback which will be called when 710 a device reset is detected. The callback is only called synchronously. 711 712 Using several contexts 713 ---------------------- 714 715 Several contexts from the same screen can be used at the same time. Objects 716 created on one context cannot be used in another context, but the objects 717 created by the screen methods can be used by all contexts. 718 719 Transfers 720 ^^^^^^^^^ 721 A transfer on one context is not expected to synchronize properly with 722 rendering on other contexts, thus only areas not yet used for rendering should 723 be locked. 724 725 A flush is required after transfer_unmap to expect other contexts to see the 726 uploaded data, unless: 727 728 * Using persistent mapping. Associated with coherent mapping, unmapping the 729 resource is also not required to use it in other contexts. Without coherent 730 mapping, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER) should be called on the 731 context that has mapped the resource. No flush is required. 732 733 * Mapping the resource with PIPE_TRANSFER_MAP_DIRECTLY. 734