6 A Gallium rendering context encapsulates the state which effects 3D
7 rendering such as blend state, depth/stencil state, texture samplers,
10 Note that resource/texture allocation is not per-context but per-screen.
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``.
24 CSO objects handled by the context object:
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``
40 Resource Binding State
41 ^^^^^^^^^^^^^^^^^^^^^^
43 This state describes how resources in various flavours (textures,
44 buffers, surfaces) are bound to the driver.
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).
52 * ``set_framebuffer_state``
54 * ``set_vertex_buffers``
56 * ``set_index_buffer``
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.
66 * ``set_stencil_ref`` sets the stencil front and back reference values
67 which are used as comparison values in stencil test.
70 * ``set_min_samples`` sets the minimum number of samples that must be run.
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
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
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
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.
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.
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.
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).
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.
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
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
137 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
138 to associated texture.
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
148 There are 2 types of shader resources: buffers and images.
150 Buffers are specified using the ``set_shader_buffers`` method.
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
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.
169 * ``create_surface`` creates a new surface.
171 * ``surface_destroy`` destroys a surface and releases its reference to the
174 Stream output targets
175 ^^^^^^^^^^^^^^^^^^^^^
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.
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.
186 Two stream output targets can use the same resource at the same time, but
187 with a disjoint memory range.
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
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
199 * ``create_stream_output_target`` create a new target.
201 * ``stream_output_target_destroy`` destroys a target. Users of this should
202 use pipe_so_target_reference instead.
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.
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
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).
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.
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.
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.
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
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.
258 For simple single-use uploads, use ``pipe_context::stream_uploader`` or
259 ``pipe_context::const_uploader``. The latter should be used for uploading
260 constants, while the former should be used for uploading everything else.
261 PIPE_USAGE_STREAM is implied in both cases, so don't use the uploaders
262 for static allocations.
266 Call u_upload_alloc or u_upload_data as many times as you want. After you are
267 done, call u_upload_unmap. If the driver doesn't support persistent mappings,
268 u_upload_unmap makes sure the previously mapped memory is unmapped.
271 - Always fill the memory immediately after u_upload_alloc. Any following call
272 to u_upload_alloc and u_upload_data can unmap memory returned by previous
274 - Don't interleave calls using stream_uploader and const_uploader. If you use
275 one of them, do the upload, unmap, and only then can you use the other one.
281 ``draw_vbo`` draws a specified primitive. The primitive mode and other
282 properties are described by ``pipe_draw_info``.
284 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the
285 the mode of the primitive and the vertices to be fetched, in the range between
286 ``start`` to ``start``+``count``-1, inclusive.
288 Every instance with instanceID in the range between ``start_instance`` and
289 ``start_instance``+``instance_count``-1, inclusive, will be drawn.
291 If there is an index buffer bound, and ``indexed`` field is true, all vertex
292 indices will be looked up in the index buffer.
294 In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower
295 and upper bound of the indices contained in the index buffer inside the range
296 between ``start`` to ``start``+``count``-1. This allows the driver to
297 determine which subset of vertices will be referenced during te draw call
298 without having to scan the index buffer. Providing a over-estimation of the
299 the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and
300 0xffffffff respectively, must give exactly the same rendering, albeit with less
301 performance due to unreferenced vertex buffers being unnecessarily DMA'ed or
302 processed. Providing a underestimation of the true bounds will result in
303 undefined behavior, but should not result in program or system failure.
305 In case of non-indexed draw, ``min_index`` should be set to
306 ``start`` and ``max_index`` should be set to ``start``+``count``-1.
308 ``index_bias`` is a value added to every vertex index after lookup and before
309 fetching vertex attributes.
311 When drawing indexed primitives, the primitive restart index can be
312 used to draw disjoint primitive strips. For example, several separate
313 line strips can be drawn by designating a special index value as the
314 restart index. The ``primitive_restart`` flag enables/disables this
315 feature. The ``restart_index`` field specifies the restart index value.
317 When primitive restart is in use, array indexes are compared to the
318 restart index before adding the index_bias offset.
320 If a given vertex element has ``instance_divisor`` set to 0, it is said
321 it contains per-vertex data and effective vertex attribute address needs
322 to be recalculated for every index.
324 attribAddr = ``stride`` * index + ``src_offset``
326 If a given vertex element has ``instance_divisor`` set to non-zero,
327 it is said it contains per-instance data and effective vertex attribute
328 address needs to recalculated for every ``instance_divisor``-th instance.
330 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
332 In the above formulas, ``src_offset`` is taken from the given vertex element
333 and ``stride`` is taken from a vertex buffer associated with the given
336 The calculated attribAddr is used as an offset into the vertex buffer to
337 fetch the attribute data.
339 The value of ``instanceID`` can be read in a vertex shader through a system
340 value register declared with INSTANCEID semantic name.
346 Queries gather some statistic from the 3D pipeline over one or more
347 draws. Queries may be nested, though not all state trackers exercise this.
349 Queries can be created with ``create_query`` and deleted with
350 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
351 use ``end_query`` to end the query.
353 ``create_query`` takes a query type (``PIPE_QUERY_*``), as well as an index,
354 which is the vertex stream for ``PIPE_QUERY_PRIMITIVES_GENERATED`` and
355 ``PIPE_QUERY_PRIMITIVES_EMITTED``, and allocates a query structure.
357 ``begin_query`` will clear/reset previous query results.
359 ``get_query_result`` is used to retrieve the results of a query. If
360 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
361 will block until the results of the query are ready (and TRUE will be
362 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
363 will not block and the return value will be TRUE if the query has
364 completed or FALSE otherwise.
366 ``get_query_result_resource`` is used to store the result of a query into
367 a resource without synchronizing with the CPU. This write will optionally
368 wait for the query to complete, and will optionally write whether the value
369 is available instead of the value itself.
371 ``set_active_query_state`` Set whether all current non-driver queries except
372 TIME_ELAPSED are active or paused.
374 The interface currently includes the following types of queries:
376 ``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which
377 are written to the framebuffer without being culled by
378 :ref:`depth-stencil-alpha` testing or shader KILL instructions.
379 The result is an unsigned 64-bit integer.
380 This query can be used with ``render_condition``.
382 In cases where a boolean result of an occlusion query is enough,
383 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
384 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
385 value of FALSE for cases where COUNTER would result in 0 and TRUE
387 This query can be used with ``render_condition``.
389 ``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
390 the context takes to perform operations.
391 The result is an unsigned 64-bit integer.
393 ``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp,
394 scaled to nanoseconds, recorded after all commands issued prior to
395 ``end_query`` have been processed.
396 This query does not require a call to ``begin_query``.
397 The result is an unsigned 64-bit integer.
399 ``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check the
400 internal timer resolution and whether the timestamp counter has become
401 unreliable due to things like throttling etc. - only if this is FALSE
402 a timestamp query (within the timestamp_disjoint query) should be trusted.
403 The result is a 64-bit integer specifying the timer resolution in Hz,
404 followed by a boolean value indicating whether the timestamp counter
405 is discontinuous or disjoint.
407 ``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating
408 the number of primitives processed by the pipeline (regardless of whether
409 stream output is active or not).
411 ``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating
412 the number of primitives written to stream output buffers.
414 ``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to
416 ``PIPE_QUERY_PRIMITIVES_EMITTED`` and
417 the number of primitives that would have been written to stream output buffers
418 if they had infinite space available (primitives_storage_needed), in this order.
419 XXX the 2nd value is equivalent to ``PIPE_QUERY_PRIMITIVES_GENERATED`` but it is
420 unclear if it should be increased if stream output is not active.
422 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
423 whether the stream output targets have overflowed as a result of the
424 commands issued between ``begin_query`` and ``end_query``.
425 This query can be used with ``render_condition``.
427 ``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
428 all commands issued before ``end_query`` have completed. However, this
429 does not imply serialization.
430 This query does not require a call to ``begin_query``.
432 ``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following
434 Number of vertices read from vertex buffers.
435 Number of primitives read from vertex buffers.
436 Number of vertex shader threads launched.
437 Number of geometry shader threads launched.
438 Number of primitives generated by geometry shaders.
439 Number of primitives forwarded to the rasterizer.
440 Number of primitives rasterized.
441 Number of fragment shader threads launched.
442 Number of tessellation control shader threads launched.
443 Number of tessellation evaluation shader threads launched.
444 If a shader type is not supported by the device/driver,
445 the corresponding values should be set to 0.
447 Gallium does not guarantee the availability of any query types; one must
448 always check the capabilities of the :ref:`Screen` first.
451 Conditional Rendering
452 ^^^^^^^^^^^^^^^^^^^^^
454 A drawing command can be skipped depending on the outcome of a query
455 (typically an occlusion query, or streamout overflow predicate).
456 The ``render_condition`` function specifies the query which should be checked
457 prior to rendering anything. Functions always honoring render_condition include
458 (and are limited to) draw_vbo and clear.
459 The blit, clear_render_target and clear_depth_stencil functions (but
460 not resource_copy_region, which seems inconsistent) can also optionally honor
461 the current render condition.
463 If ``render_condition`` is called with ``query`` = NULL, conditional
464 rendering is disabled and drawing takes place normally.
466 If ``render_condition`` is called with a non-null ``query`` subsequent
467 drawing commands will be predicated on the outcome of the query.
468 Commands will be skipped if ``condition`` is equal to the predicate result
469 (for non-boolean queries such as OCCLUSION_QUERY, zero counts as FALSE,
472 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
473 query to complete before deciding whether to render.
475 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
476 completed, the drawing command will be executed normally. If the query
477 has completed, drawing will be predicated on the outcome of the query.
479 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
480 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
481 for the non-REGION modes but in the case that an occlusion query returns
482 a non-zero result, regions which were occluded may be ommitted by subsequent
483 drawing commands. This can result in better performance with some GPUs.
484 Normally, if the occlusion query returned a non-zero result subsequent
485 drawing happens normally so fragments may be generated, shaded and
486 processed even where they're known to be obscured.
494 PIPE_FLUSH_END_OF_FRAME: Whether the flush marks the end of frame.
496 PIPE_FLUSH_DEFERRED: It is not required to flush right away, but it is required
497 to return a valid fence. If fence_finish is called with the returned fence
498 and the context is still unflushed, and the ctx parameter of fence_finish is
499 equal to the context where the fence was created, fence_finish will flush
505 Flush the resource cache, so that the resource can be used
506 by an external client. Possible usage:
507 - flushing a resource before presenting it on the screen
508 - flushing a resource if some other process or device wants to use it
509 This shouldn't be used to flush caches if the resource is only managed
510 by a single pipe_screen and is not shared with another process.
511 (i.e. you shouldn't use it to flush caches explicitly if you want to e.g.
512 use the resource for texturing)
516 Resource Busy Queries
517 ^^^^^^^^^^^^^^^^^^^^^
519 ``is_resource_referenced``
526 These methods emulate classic blitter controls.
528 These methods operate directly on ``pipe_resource`` objects, and stand
529 apart from any 3D state in the context. Blitting functionality may be
530 moved to a separate abstraction at some point in the future.
532 ``resource_copy_region`` blits a region of a resource to a region of another
533 resource, provided that both resources have the same format, or compatible
534 formats, i.e., formats for which copying the bytes from the source resource
535 unmodified to the destination resource will achieve the same effect of a
536 textured quad blitter.. The source and destination may be the same resource,
537 but overlapping blits are not permitted.
538 This can be considered the equivalent of a CPU memcpy.
540 ``blit`` blits a region of a resource to a region of another resource, including
541 scaling, format conversion, and up-/downsampling, as well as a destination clip
542 rectangle (scissors) and window rectangles. It can also optionally honor the
543 current render condition (but either way the blit itself never contributes
544 anything to queries currently gathering data).
545 As opposed to manually drawing a textured quad, this lets the pipe driver choose
546 the optimal method for blitting (like using a special 2D engine), and usually
547 offers, for example, accelerated stencil-only copies even where
548 PIPE_CAP_SHADER_STENCIL_EXPORT is not available.
554 These methods are used to get data to/from a resource.
556 ``transfer_map`` creates a memory mapping and the transfer object
558 The returned pointer points to the start of the mapped range according to
559 the box region, not the beginning of the resource. If transfer_map fails,
560 the returned pointer to the buffer memory is NULL, and the pointer
561 to the transfer object remains unchanged (i.e. it can be non-NULL).
563 ``transfer_unmap`` remove the memory mapping for and destroy
564 the transfer object. The pointer into the resource should be considered
565 invalid and discarded.
567 ``texture_subdata`` and ``buffer_subdata`` perform a simplified
568 transfer for simple writes. Basically transfer_map, data write, and
569 transfer_unmap all in one.
572 The box parameter to some of these functions defines a 1D, 2D or 3D
573 region of pixels. This is self-explanatory for 1D, 2D and 3D texture
576 For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth
577 fields refer to the array dimension of the texture.
579 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
580 faces of the cube map (z + depth <= 6).
582 For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both
583 the face and array dimension of the texture (face = z % 6, array = z / 6).
586 .. _transfer_flush_region:
588 transfer_flush_region
589 %%%%%%%%%%%%%%%%%%%%%
591 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
592 be flushed on write or unmap. Flushes must be requested with
593 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
594 the beginning of the resource.
603 This function flushes all pending writes to the currently-set surfaces and
604 invalidates all read caches of the currently-set samplers. This can be used
605 for both regular textures as well as for framebuffers read via FBFETCH.
614 This function flushes caches according to which of the PIPE_BARRIER_* flags
624 These flags control the behavior of a transfer object.
626 ``PIPE_TRANSFER_READ``
627 Resource contents read back (or accessed directly) at transfer create time.
629 ``PIPE_TRANSFER_WRITE``
630 Resource contents will be written back at transfer_unmap time (or modified
631 as a result of being accessed directly).
633 ``PIPE_TRANSFER_MAP_DIRECTLY``
634 a transfer should directly map the resource. May return NULL if not supported.
636 ``PIPE_TRANSFER_DISCARD_RANGE``
637 The memory within the mapped region is discarded. Cannot be used with
638 ``PIPE_TRANSFER_READ``.
640 ``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE``
641 Discards all memory backing the resource. It should not be used with
642 ``PIPE_TRANSFER_READ``.
644 ``PIPE_TRANSFER_DONTBLOCK``
645 Fail if the resource cannot be mapped immediately.
647 ``PIPE_TRANSFER_UNSYNCHRONIZED``
648 Do not synchronize pending operations on the resource when mapping. The
649 interaction of any writes to the map and any operations pending on the
650 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``.
652 ``PIPE_TRANSFER_FLUSH_EXPLICIT``
653 Written ranges will be notified later with :ref:`transfer_flush_region`.
654 Cannot be used with ``PIPE_TRANSFER_READ``.
656 ``PIPE_TRANSFER_PERSISTENT``
657 Allows the resource to be used for rendering while mapped.
658 PIPE_RESOURCE_FLAG_MAP_PERSISTENT must be set when creating
660 If COHERENT is not set, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER)
661 must be called to ensure the device can see what the CPU has written.
663 ``PIPE_TRANSFER_COHERENT``
664 If PERSISTENT is set, this ensures any writes done by the device are
665 immediately visible to the CPU and vice versa.
666 PIPE_RESOURCE_FLAG_MAP_COHERENT must be set when creating
669 Compute kernel execution
670 ^^^^^^^^^^^^^^^^^^^^^^^^
672 A compute program can be defined, bound or destroyed using
673 ``create_compute_state``, ``bind_compute_state`` or
674 ``destroy_compute_state`` respectively.
676 Any of the subroutines contained within the compute program can be
677 executed on the device using the ``launch_grid`` method. This method
678 will execute as many instances of the program as elements in the
679 specified N-dimensional grid, hopefully in parallel.
681 The compute program has access to four special resources:
683 * ``GLOBAL`` represents a memory space shared among all the threads
684 running on the device. An arbitrary buffer created with the
685 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the
686 ``set_global_binding`` method.
688 * ``LOCAL`` represents a memory space shared among all the threads
689 running in the same working group. The initial contents of this
690 resource are undefined.
692 * ``PRIVATE`` represents a memory space local to a single thread.
693 The initial contents of this resource are undefined.
695 * ``INPUT`` represents a read-only memory space that can be
696 initialized at ``launch_grid`` time.
698 These resources use a byte-based addressing scheme, and they can be
699 accessed from the compute program by means of the LOAD/STORE TGSI
700 opcodes. Additional resources to be accessed using the same opcodes
701 may be specified by the user with the ``set_compute_resources``
704 In addition, normal texture sampling is allowed from the compute
705 program: ``bind_sampler_states`` may be used to set up texture
706 samplers for the compute stage and ``set_sampler_views`` may
707 be used to bind a number of sampler views to it.
712 If PIPE_CAP_GENERATE_MIPMAP is true, ``generate_mipmap`` can be used
713 to generate mipmaps for the specified texture resource.
714 It replaces texel image levels base_level+1 through
715 last_level for layers range from first_layer through last_layer.
716 It returns TRUE if mipmap generation succeeds, otherwise it
717 returns FALSE. Mipmap generation may fail when it is not supported
718 for particular texture types or formats.
723 The state tracker can query or request notifications of when the GPU
724 is reset for whatever reason (application error, driver error). When
725 a GPU reset happens, the context becomes unusable and all related state
726 should be considered lost and undefined. Despite that, context
727 notifications are single-shot, i.e. subsequent calls to
728 ``get_device_reset_status`` will return PIPE_NO_RESET.
730 * ``get_device_reset_status`` queries whether a device reset has happened
731 since the last call or since the last notification by callback.
732 * ``set_device_reset_callback`` sets a callback which will be called when
733 a device reset is detected. The callback is only called synchronously.
735 Using several contexts
736 ----------------------
738 Several contexts from the same screen can be used at the same time. Objects
739 created on one context cannot be used in another context, but the objects
740 created by the screen methods can be used by all contexts.
744 A transfer on one context is not expected to synchronize properly with
745 rendering on other contexts, thus only areas not yet used for rendering should
748 A flush is required after transfer_unmap to expect other contexts to see the
749 uploaded data, unless:
751 * Using persistent mapping. Associated with coherent mapping, unmapping the
752 resource is also not required to use it in other contexts. Without coherent
753 mapping, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER) should be called on the
754 context that has mapped the resource. No flush is required.
756 * Mapping the resource with PIPE_TRANSFER_MAP_DIRECTLY.