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:`Vertex Elements`: ``*_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.
71 * ``set_polygon_stipple``
72 * ``set_scissor_states`` sets the bounds for the scissor test, which culls
73 pixels before blending to render targets. If the :ref:`Rasterizer` does
74 not have the scissor test enabled, then the scissor bounds never need to
75 be set since they will not be used. Note that scissor xmin and ymin are
76 inclusive, but xmax and ymax are exclusive. The inclusive ranges in x
77 and y would be [xmin..xmax-1] and [ymin..ymax-1]. The number of scissors
78 should be the same as the number of set viewports and can be up to
80 * ``set_viewport_states``
86 These are the means to bind textures to shader stages. To create one, specify
87 its format, swizzle and LOD range in sampler view template.
89 If texture format is different than template format, it is said the texture
90 is being cast to another format. Casting can be done only between compatible
91 formats, that is formats that have matching component order and sizes.
93 Swizzle fields specify they way in which fetched texel components are placed
94 in the result register. For example, ``swizzle_r`` specifies what is going to be
95 placed in first component of result register.
97 The ``first_level`` and ``last_level`` fields of sampler view template specify
98 the LOD range the texture is going to be constrained to. Note that these
99 values are in addition to the respective min_lod, max_lod values in the
100 pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip
101 level used for sampling from the resource is effectively the fifth).
103 The ``first_layer`` and ``last_layer`` fields specify the layer range the
104 texture is going to be constrained to. Similar to the LOD range, this is added
105 to the array index which is used for sampling.
107 * ``set_sampler_views`` binds an array of sampler views to a shader stage.
108 Every binding point acquires a reference
109 to a respective sampler view and releases a reference to the previous
112 * ``create_sampler_view`` creates a new sampler view. ``texture`` is associated
113 with the sampler view which results in sampler view holding a reference
114 to the texture. Format specified in template must be compatible
117 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
118 to associated texture.
123 Shader resources are textures or buffers that may be read or written
124 from a shader without an associated sampler. This means that they
125 have no support for floating point coordinates, address wrap modes or
128 Shader resources are specified for all the shader stages at once using
129 the ``set_shader_resources`` method. When binding texture resources,
130 the ``level``, ``first_layer`` and ``last_layer`` pipe_surface fields
131 specify the mipmap level and the range of layers the texture will be
132 constrained to. In the case of buffers, ``first_element`` and
133 ``last_element`` specify the range within the buffer that will be used
134 by the shader resource. Writes to a shader resource are only allowed
135 when the ``writable`` flag is set.
140 These are the means to use resources as color render targets or depthstencil
141 attachments. To create one, specify the mip level, the range of layers, and
142 the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
143 Note that layer values are in addition to what is indicated by the geometry
144 shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
145 shader indicates index 2, the 5th layer of the resource will be used). These
146 first_layer and last_layer parameters will only be used for 1d array, 2d array,
147 cube, and 3d textures otherwise they are 0.
149 * ``create_surface`` creates a new surface.
151 * ``surface_destroy`` destroys a surface and releases its reference to the
154 Stream output targets
155 ^^^^^^^^^^^^^^^^^^^^^
157 Stream output, also known as transform feedback, allows writing the primitives
158 produced by the vertex pipeline to buffers. This is done after the geometry
159 shader or vertex shader if no geometry shader is present.
161 The stream output targets are views into buffer resources which can be bound
162 as stream outputs and specify a memory range where it's valid to write
163 primitives. The pipe driver must implement memory protection such that any
164 primitives written outside of the specified memory range are discarded.
166 Two stream output targets can use the same resource at the same time, but
167 with a disjoint memory range.
169 Additionally, the stream output target internally maintains the offset
170 into the buffer which is incremented everytime something is written to it.
171 The internal offset is equal to how much data has already been written.
172 It can be stored in device memory and the CPU actually doesn't have to query
175 The stream output target can be used in a draw command to provide
176 the vertex count. The vertex count is derived from the internal offset
179 * ``create_stream_output_target`` create a new target.
181 * ``stream_output_target_destroy`` destroys a target. Users of this should
182 use pipe_so_target_reference instead.
184 * ``set_stream_output_targets`` binds stream output targets. The parameter
185 offset is an array which specifies the internal offset of the buffer. The
186 internal offset is, besides writing, used for reading the data during the
187 draw_auto stage, i.e. it specifies how much data there is in the buffer
188 for the purposes of the draw_auto stage. -1 means the buffer should
189 be appended to, and everything else sets the internal offset.
191 NOTE: The currently-bound vertex or geometry shader must be compiled with
192 the properly-filled-in structure pipe_stream_output_info describing which
193 outputs should be written to buffers and how. The structure is part of
199 Clear is one of the most difficult concepts to nail down to a single
200 interface (due to both different requirements from APIs and also driver/hw
201 specific differences).
203 ``clear`` initializes some or all of the surfaces currently bound to
204 the framebuffer to particular RGBA, depth, or stencil values.
205 Currently, this does not take into account color or stencil write masks (as
206 used by GL), and always clears the whole surfaces (no scissoring as used by
207 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
208 only depth or stencil in a combined depth/stencil surface.
209 If a surface includes several layers then all layers will be cleared.
211 ``clear_render_target`` clears a single color rendertarget with the specified
212 color value. While it is only possible to clear one surface at a time (which can
213 include several layers), this surface need not be bound to the framebuffer.
215 ``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface
216 with the specified depth and stencil values (for combined depth/stencil buffers,
217 is is also possible to only clear one or the other part). While it is only
218 possible to clear one surface at a time (which can include several layers),
219 this surface need not be bound to the framebuffer.
221 ``clear_buffer`` clears a PIPE_BUFFER resource with the specified clear value
222 (which may be multiple bytes in length). Logically this is a memset with a
223 multi-byte element value starting at offset bytes from resource start, going
224 for size bytes. It is guaranteed that size % clear_value_size == 0.
230 ``draw_vbo`` draws a specified primitive. The primitive mode and other
231 properties are described by ``pipe_draw_info``.
233 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the
234 the mode of the primitive and the vertices to be fetched, in the range between
235 ``start`` to ``start``+``count``-1, inclusive.
237 Every instance with instanceID in the range between ``start_instance`` and
238 ``start_instance``+``instance_count``-1, inclusive, will be drawn.
240 If there is an index buffer bound, and ``indexed`` field is true, all vertex
241 indices will be looked up in the index buffer.
243 In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower
244 and upper bound of the indices contained in the index buffer inside the range
245 between ``start`` to ``start``+``count``-1. This allows the driver to
246 determine which subset of vertices will be referenced during te draw call
247 without having to scan the index buffer. Providing a over-estimation of the
248 the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and
249 0xffffffff respectively, must give exactly the same rendering, albeit with less
250 performance due to unreferenced vertex buffers being unnecessarily DMA'ed or
251 processed. Providing a underestimation of the true bounds will result in
252 undefined behavior, but should not result in program or system failure.
254 In case of non-indexed draw, ``min_index`` should be set to
255 ``start`` and ``max_index`` should be set to ``start``+``count``-1.
257 ``index_bias`` is a value added to every vertex index after lookup and before
258 fetching vertex attributes.
260 When drawing indexed primitives, the primitive restart index can be
261 used to draw disjoint primitive strips. For example, several separate
262 line strips can be drawn by designating a special index value as the
263 restart index. The ``primitive_restart`` flag enables/disables this
264 feature. The ``restart_index`` field specifies the restart index value.
266 When primitive restart is in use, array indexes are compared to the
267 restart index before adding the index_bias offset.
269 If a given vertex element has ``instance_divisor`` set to 0, it is said
270 it contains per-vertex data and effective vertex attribute address needs
271 to be recalculated for every index.
273 attribAddr = ``stride`` * index + ``src_offset``
275 If a given vertex element has ``instance_divisor`` set to non-zero,
276 it is said it contains per-instance data and effective vertex attribute
277 address needs to recalculated for every ``instance_divisor``-th instance.
279 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
281 In the above formulas, ``src_offset`` is taken from the given vertex element
282 and ``stride`` is taken from a vertex buffer associated with the given
285 The calculated attribAddr is used as an offset into the vertex buffer to
286 fetch the attribute data.
288 The value of ``instanceID`` can be read in a vertex shader through a system
289 value register declared with INSTANCEID semantic name.
295 Queries gather some statistic from the 3D pipeline over one or more
296 draws. Queries may be nested, though not all state trackers exercise this.
298 Queries can be created with ``create_query`` and deleted with
299 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
300 use ``end_query`` to end the query.
302 ``get_query_result`` is used to retrieve the results of a query. If
303 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
304 will block until the results of the query are ready (and TRUE will be
305 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
306 will not block and the return value will be TRUE if the query has
307 completed or FALSE otherwise.
309 The interface currently includes the following types of queries:
311 ``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which
312 are written to the framebuffer without being culled by
313 :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
314 The result is an unsigned 64-bit integer.
315 This query can be used with ``render_condition``.
317 In cases where a boolean result of an occlusion query is enough,
318 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
319 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
320 value of FALSE for cases where COUNTER would result in 0 and TRUE
322 This query can be used with ``render_condition``.
324 ``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
325 the context takes to perform operations.
326 The result is an unsigned 64-bit integer.
328 ``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp,
329 scaled to nanoseconds, recorded after all commands issued prior to
330 ``end_query`` have been processed.
331 This query does not require a call to ``begin_query``.
332 The result is an unsigned 64-bit integer.
334 ``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check the
335 internal timer resolution and whether the timestamp counter has become
336 unreliable due to things like throttling etc. - only if this is FALSE
337 a timestamp query (within the timestamp_disjoint query) should be trusted.
338 The result is a 64-bit integer specifying the timer resolution in Hz,
339 followed by a boolean value indicating whether the timestamp counter
340 is discontinuous or disjoint.
342 ``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating
343 the number of primitives processed by the pipeline (regardless of whether
344 stream output is active or not).
346 ``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating
347 the number of primitives written to stream output buffers.
349 ``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to
351 ``PIPE_QUERY_PRIMITIVES_EMITTED`` and
352 the number of primitives that would have been written to stream output buffers
353 if they had infinite space available (primitives_storage_needed), in this order.
354 XXX the 2nd value is equivalent to ``PIPE_QUERY_PRIMITIVES_GENERATED`` but it is
355 unclear if it should be increased if stream output is not active.
357 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
358 whether the stream output targets have overflowed as a result of the
359 commands issued between ``begin_query`` and ``end_query``.
360 This query can be used with ``render_condition``.
362 ``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
363 all commands issued before ``end_query`` have completed. However, this
364 does not imply serialization.
365 This query does not require a call to ``begin_query``.
367 ``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following
369 Number of vertices read from vertex buffers.
370 Number of primitives read from vertex buffers.
371 Number of vertex shader threads launched.
372 Number of geometry shader threads launched.
373 Number of primitives generated by geometry shaders.
374 Number of primitives forwarded to the rasterizer.
375 Number of primitives rasterized.
376 Number of fragment shader threads launched.
377 Number of tessellation control shader threads launched.
378 Number of tessellation evaluation shader threads launched.
379 If a shader type is not supported by the device/driver,
380 the corresponding values should be set to 0.
382 Gallium does not guarantee the availability of any query types; one must
383 always check the capabilities of the :ref:`Screen` first.
386 Conditional Rendering
387 ^^^^^^^^^^^^^^^^^^^^^
389 A drawing command can be skipped depending on the outcome of a query
390 (typically an occlusion query, or streamout overflow predicate).
391 The ``render_condition`` function specifies the query which should be checked
392 prior to rendering anything. Functions honoring render_condition include
393 (and are limited to) draw_vbo, clear, clear_render_target, clear_depth_stencil.
395 If ``render_condition`` is called with ``query`` = NULL, conditional
396 rendering is disabled and drawing takes place normally.
398 If ``render_condition`` is called with a non-null ``query`` subsequent
399 drawing commands will be predicated on the outcome of the query.
400 Commands will be skipped if ``condition`` is equal to the predicate result
401 (for non-boolean queries such as OCCLUSION_QUERY, zero counts as FALSE,
404 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
405 query to complete before deciding whether to render.
407 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
408 completed, the drawing command will be executed normally. If the query
409 has completed, drawing will be predicated on the outcome of the query.
411 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
412 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
413 for the non-REGION modes but in the case that an occlusion query returns
414 a non-zero result, regions which were occluded may be ommitted by subsequent
415 drawing commands. This can result in better performance with some GPUs.
416 Normally, if the occlusion query returned a non-zero result subsequent
417 drawing happens normally so fragments may be generated, shaded and
418 processed even where they're known to be obscured.
429 Flush the resource cache, so that the resource can be used
430 by an external client. Possible usage:
431 - flushing a resource before presenting it on the screen
432 - flushing a resource if some other process or device wants to use it
433 This shouldn't be used to flush caches if the resource is only managed
434 by a single pipe_screen and is not shared with another process.
435 (i.e. you shouldn't use it to flush caches explicitly if you want to e.g.
436 use the resource for texturing)
440 Resource Busy Queries
441 ^^^^^^^^^^^^^^^^^^^^^
443 ``is_resource_referenced``
450 These methods emulate classic blitter controls.
452 These methods operate directly on ``pipe_resource`` objects, and stand
453 apart from any 3D state in the context. Blitting functionality may be
454 moved to a separate abstraction at some point in the future.
456 ``resource_copy_region`` blits a region of a resource to a region of another
457 resource, provided that both resources have the same format, or compatible
458 formats, i.e., formats for which copying the bytes from the source resource
459 unmodified to the destination resource will achieve the same effect of a
460 textured quad blitter.. The source and destination may be the same resource,
461 but overlapping blits are not permitted.
462 This can be considered the equivalent of a CPU memcpy.
464 ``blit`` blits a region of a resource to a region of another resource, including
465 scaling, format conversion, and up-/downsampling, as well as
466 a destination clip rectangle (scissors).
467 As opposed to manually drawing a textured quad, this lets the pipe driver choose
468 the optimal method for blitting (like using a special 2D engine), and usually
469 offers, for example, accelerated stencil-only copies even where
470 PIPE_CAP_SHADER_STENCIL_EXPORT is not available.
476 These methods are used to get data to/from a resource.
478 ``transfer_map`` creates a memory mapping and the transfer object
480 The returned pointer points to the start of the mapped range according to
481 the box region, not the beginning of the resource. If transfer_map fails,
482 the returned pointer to the buffer memory is NULL, and the pointer
483 to the transfer object remains unchanged (i.e. it can be non-NULL).
485 ``transfer_unmap`` remove the memory mapping for and destroy
486 the transfer object. The pointer into the resource should be considered
487 invalid and discarded.
489 ``transfer_inline_write`` performs a simplified transfer for simple writes.
490 Basically transfer_map, data write, and transfer_unmap all in one.
493 The box parameter to some of these functions defines a 1D, 2D or 3D
494 region of pixels. This is self-explanatory for 1D, 2D and 3D texture
497 For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth
498 fields refer to the array dimension of the texture.
500 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
501 faces of the cube map (z + depth <= 6).
503 For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both
504 the face and array dimension of the texture (face = z % 6, array = z / 6).
507 .. _transfer_flush_region:
509 transfer_flush_region
510 %%%%%%%%%%%%%%%%%%%%%
512 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
513 be flushed on write or unmap. Flushes must be requested with
514 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
515 the beginning of the resource.
524 This function flushes all pending writes to the currently-set surfaces and
525 invalidates all read caches of the currently-set samplers.
534 This function flushes caches according to which of the PIPE_BARRIER_* flags
544 These flags control the behavior of a transfer object.
546 ``PIPE_TRANSFER_READ``
547 Resource contents read back (or accessed directly) at transfer create time.
549 ``PIPE_TRANSFER_WRITE``
550 Resource contents will be written back at transfer_unmap time (or modified
551 as a result of being accessed directly).
553 ``PIPE_TRANSFER_MAP_DIRECTLY``
554 a transfer should directly map the resource. May return NULL if not supported.
556 ``PIPE_TRANSFER_DISCARD_RANGE``
557 The memory within the mapped region is discarded. Cannot be used with
558 ``PIPE_TRANSFER_READ``.
560 ``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE``
561 Discards all memory backing the resource. It should not be used with
562 ``PIPE_TRANSFER_READ``.
564 ``PIPE_TRANSFER_DONTBLOCK``
565 Fail if the resource cannot be mapped immediately.
567 ``PIPE_TRANSFER_UNSYNCHRONIZED``
568 Do not synchronize pending operations on the resource when mapping. The
569 interaction of any writes to the map and any operations pending on the
570 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``.
572 ``PIPE_TRANSFER_FLUSH_EXPLICIT``
573 Written ranges will be notified later with :ref:`transfer_flush_region`.
574 Cannot be used with ``PIPE_TRANSFER_READ``.
576 ``PIPE_TRANSFER_PERSISTENT``
577 Allows the resource to be used for rendering while mapped.
578 PIPE_RESOURCE_FLAG_MAP_PERSISTENT must be set when creating
580 If COHERENT is not set, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER)
581 must be called to ensure the device can see what the CPU has written.
583 ``PIPE_TRANSFER_COHERENT``
584 If PERSISTENT is set, this ensures any writes done by the device are
585 immediately visible to the CPU and vice versa.
586 PIPE_RESOURCE_FLAG_MAP_COHERENT must be set when creating
589 Compute kernel execution
590 ^^^^^^^^^^^^^^^^^^^^^^^^
592 A compute program can be defined, bound or destroyed using
593 ``create_compute_state``, ``bind_compute_state`` or
594 ``destroy_compute_state`` respectively.
596 Any of the subroutines contained within the compute program can be
597 executed on the device using the ``launch_grid`` method. This method
598 will execute as many instances of the program as elements in the
599 specified N-dimensional grid, hopefully in parallel.
601 The compute program has access to four special resources:
603 * ``GLOBAL`` represents a memory space shared among all the threads
604 running on the device. An arbitrary buffer created with the
605 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the
606 ``set_global_binding`` method.
608 * ``LOCAL`` represents a memory space shared among all the threads
609 running in the same working group. The initial contents of this
610 resource are undefined.
612 * ``PRIVATE`` represents a memory space local to a single thread.
613 The initial contents of this resource are undefined.
615 * ``INPUT`` represents a read-only memory space that can be
616 initialized at ``launch_grid`` time.
618 These resources use a byte-based addressing scheme, and they can be
619 accessed from the compute program by means of the LOAD/STORE TGSI
620 opcodes. Additional resources to be accessed using the same opcodes
621 may be specified by the user with the ``set_compute_resources``
624 In addition, normal texture sampling is allowed from the compute
625 program: ``bind_sampler_states`` may be used to set up texture
626 samplers for the compute stage and ``set_sampler_views`` may
627 be used to bind a number of sampler views to it.