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 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``
39 Resource Binding State
40 ^^^^^^^^^^^^^^^^^^^^^^
42 This state describes how resources in various flavours (textures,
43 buffers, surfaces) are bound to the driver.
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).
51 * ``set_framebuffer_state``
53 * ``set_vertex_buffers``
55 * ``set_index_buffer``
61 These pieces of state are too small, variable, and/or trivial to have CSO
62 objects. They all follow simple, one-method binding calls, e.g.
65 * ``set_stencil_ref`` sets the stencil front and back reference values
66 which are used as comparison values in stencil test.
70 * ``set_polygon_stipple``
71 * ``set_scissor_states`` 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]. The number of scissors
77 should be the same as the number of set viewports and can be up to
79 * ``set_viewport_states``
85 These are the means to bind textures to shader stages. To create one, specify
86 its format, swizzle and LOD range in sampler view template.
88 If texture format is different than template format, it is said the texture
89 is being cast to another format. Casting can be done only between compatible
90 formats, that is formats that have matching component order and sizes.
92 Swizzle fields specify they way in which fetched texel components are placed
93 in the result register. For example, ``swizzle_r`` specifies what is going to be
94 placed in first component of result register.
96 The ``first_level`` and ``last_level`` fields of sampler view template specify
97 the LOD range the texture is going to be constrained to. Note that these
98 values are in addition to the respective min_lod, max_lod values in the
99 pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip
100 level used for sampling from the resource is effectively the fifth).
102 The ``first_layer`` and ``last_layer`` fields specify the layer range the
103 texture is going to be constrained to. Similar to the LOD range, this is added
104 to the array index which is used for sampling.
106 * ``set_fragment_sampler_views`` binds an array of sampler views to
107 fragment shader stage. Every binding point acquires a reference
108 to a respective sampler view and releases a reference to the previous
109 sampler view. If M is the maximum number of sampler units and N units
110 is passed to set_fragment_sampler_views, the driver should unbind the
111 sampler views for units N..M-1.
113 * ``set_vertex_sampler_views`` binds an array of sampler views to vertex
114 shader stage. Every binding point acquires a reference to a respective
115 sampler view and releases a reference to the previous sampler view.
117 * ``create_sampler_view`` creates a new sampler view. ``texture`` is associated
118 with the sampler view which results in sampler view holding a reference
119 to the texture. Format specified in template must be compatible
122 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
123 to associated texture.
128 Shader resources are textures or buffers that may be read or written
129 from a shader without an associated sampler. This means that they
130 have no support for floating point coordinates, address wrap modes or
133 Shader resources are specified for all the shader stages at once using
134 the ``set_shader_resources`` method. When binding texture resources,
135 the ``level``, ``first_layer`` and ``last_layer`` pipe_surface fields
136 specify the mipmap level and the range of layers the texture will be
137 constrained to. In the case of buffers, ``first_element`` and
138 ``last_element`` specify the range within the buffer that will be used
139 by the shader resource. Writes to a shader resource are only allowed
140 when the ``writable`` flag is set.
145 These are the means to use resources as color render targets or depthstencil
146 attachments. To create one, specify the mip level, the range of layers, and
147 the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
148 Note that layer values are in addition to what is indicated by the geometry
149 shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
150 shader indicates index 2, the 5th layer of the resource will be used). These
151 first_layer and last_layer parameters will only be used for 1d array, 2d array,
152 cube, and 3d textures otherwise they are 0.
154 * ``create_surface`` creates a new surface.
156 * ``surface_destroy`` destroys a surface and releases its reference to the
159 Stream output targets
160 ^^^^^^^^^^^^^^^^^^^^^
162 Stream output, also known as transform feedback, allows writing the primitives
163 produced by the vertex pipeline to buffers. This is done after the geometry
164 shader or vertex shader if no geometry shader is present.
166 The stream output targets are views into buffer resources which can be bound
167 as stream outputs and specify a memory range where it's valid to write
168 primitives. The pipe driver must implement memory protection such that any
169 primitives written outside of the specified memory range are discarded.
171 Two stream output targets can use the same resource at the same time, but
172 with a disjoint memory range.
174 Additionally, the stream output target internally maintains the offset
175 into the buffer which is incremented everytime something is written to it.
176 The internal offset is equal to how much data has already been written.
177 It can be stored in device memory and the CPU actually doesn't have to query
180 The stream output target can be used in a draw command to provide
181 the vertex count. The vertex count is derived from the internal offset
184 * ``create_stream_output_target`` create a new target.
186 * ``stream_output_target_destroy`` destroys a target. Users of this should
187 use pipe_so_target_reference instead.
189 * ``set_stream_output_targets`` binds stream output targets. The parameter
190 append_bitmask is a bitmask, where the i-th bit specifies whether new
191 primitives should be appended to the i-th buffer (writing starts at
192 the internal offset), or whether writing should start at the beginning
193 (the internal offset is effectively set to 0).
195 NOTE: The currently-bound vertex or geometry shader must be compiled with
196 the properly-filled-in structure pipe_stream_output_info describing which
197 outputs should be written to buffers and how. The structure is part of
203 Clear is one of the most difficult concepts to nail down to a single
204 interface (due to both different requirements from APIs and also driver/hw
205 specific differences).
207 ``clear`` initializes some or all of the surfaces currently bound to
208 the framebuffer to particular RGBA, depth, or stencil values.
209 Currently, this does not take into account color or stencil write masks (as
210 used by GL), and always clears the whole surfaces (no scissoring as used by
211 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
212 only depth or stencil in a combined depth/stencil surface.
213 If a surface includes several layers then all layers will be cleared.
215 ``clear_render_target`` clears a single color rendertarget with the specified
216 color value. While it is only possible to clear one surface at a time (which can
217 include several layers), this surface need not be bound to the framebuffer.
219 ``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface
220 with the specified depth and stencil values (for combined depth/stencil buffers,
221 is is also possible to only clear one or the other part). While it is only
222 possible to clear one surface at a time (which can include several layers),
223 this surface need not be bound to the framebuffer.
229 ``draw_vbo`` draws a specified primitive. The primitive mode and other
230 properties are described by ``pipe_draw_info``.
232 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the
233 the mode of the primitive and the vertices to be fetched, in the range between
234 ``start`` to ``start``+``count``-1, inclusive.
236 Every instance with instanceID in the range between ``start_instance`` and
237 ``start_instance``+``instance_count``-1, inclusive, will be drawn.
239 If there is an index buffer bound, and ``indexed`` field is true, all vertex
240 indices will be looked up in the index buffer.
242 In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower
243 and upper bound of the indices contained in the index buffer inside the range
244 between ``start`` to ``start``+``count``-1. This allows the driver to
245 determine which subset of vertices will be referenced during te draw call
246 without having to scan the index buffer. Providing a over-estimation of the
247 the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and
248 0xffffffff respectively, must give exactly the same rendering, albeit with less
249 performance due to unreferenced vertex buffers being unnecessarily DMA'ed or
250 processed. Providing a underestimation of the true bounds will result in
251 undefined behavior, but should not result in program or system failure.
253 In case of non-indexed draw, ``min_index`` should be set to
254 ``start`` and ``max_index`` should be set to ``start``+``count``-1.
256 ``index_bias`` is a value added to every vertex index after lookup and before
257 fetching vertex attributes.
259 When drawing indexed primitives, the primitive restart index can be
260 used to draw disjoint primitive strips. For example, several separate
261 line strips can be drawn by designating a special index value as the
262 restart index. The ``primitive_restart`` flag enables/disables this
263 feature. The ``restart_index`` field specifies the restart index value.
265 When primitive restart is in use, array indexes are compared to the
266 restart index before adding the index_bias offset.
268 If a given vertex element has ``instance_divisor`` set to 0, it is said
269 it contains per-vertex data and effective vertex attribute address needs
270 to be recalculated for every index.
272 attribAddr = ``stride`` * index + ``src_offset``
274 If a given vertex element has ``instance_divisor`` set to non-zero,
275 it is said it contains per-instance data and effective vertex attribute
276 address needs to recalculated for every ``instance_divisor``-th instance.
278 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
280 In the above formulas, ``src_offset`` is taken from the given vertex element
281 and ``stride`` is taken from a vertex buffer associated with the given
284 The calculated attribAddr is used as an offset into the vertex buffer to
285 fetch the attribute data.
287 The value of ``instanceID`` can be read in a vertex shader through a system
288 value register declared with INSTANCEID semantic name.
294 Queries gather some statistic from the 3D pipeline over one or more
295 draws. Queries may be nested, though not all state trackers exercise this.
297 Queries can be created with ``create_query`` and deleted with
298 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
299 use ``end_query`` to end the query.
301 ``get_query_result`` is used to retrieve the results of a query. If
302 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
303 will block until the results of the query are ready (and TRUE will be
304 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
305 will not block and the return value will be TRUE if the query has
306 completed or FALSE otherwise.
308 The interface currently includes the following types of queries:
310 ``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which
311 are written to the framebuffer without being culled by
312 :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
313 The result is an unsigned 64-bit integer.
314 This query can be used with ``render_condition``.
316 In cases where a boolean result of an occlusion query is enough,
317 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
318 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
319 value of FALSE for cases where COUNTER would result in 0 and TRUE
321 This query can be used with ``render_condition``.
323 ``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
324 the context takes to perform operations.
325 The result is an unsigned 64-bit integer.
327 ``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp,
328 scaled to nanoseconds, recorded after all commands issued prior to
329 ``end_query`` have been processed.
330 This query does not require a call to ``begin_query``.
331 The result is an unsigned 64-bit integer.
333 ``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check whether the
334 internal timer resolution is good enough to distinguish between the
335 events at ``begin_query`` and ``end_query``.
336 The result is a 64-bit integer specifying the timer resolution in Hz,
337 followed by a boolean value indicating whether the timer has incremented.
339 ``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating
340 the number of primitives processed by the pipeline (regardless of whether
341 stream output is active or not).
343 ``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating
344 the number of primitives written to stream output buffers.
346 ``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to
348 ``PIPE_QUERY_PRIMITIVES_EMITTED`` and
349 the number of primitives that would have been written to stream output buffers
350 if they had infinite space available (primitives_storage_needed), in this order.
352 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
353 whether the stream output targets have overflowed as a result of the
354 commands issued between ``begin_query`` and ``end_query``.
355 This query can be used with ``render_condition``.
357 ``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
358 all commands issued before ``end_query`` have completed. However, this
359 does not imply serialization.
360 This query does not require a call to ``begin_query``.
362 ``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following
364 Number of vertices read from vertex buffers.
365 Number of primitives read from vertex buffers.
366 Number of vertex shader threads launched.
367 Number of geometry shader threads launched.
368 Number of primitives generated by geometry shaders.
369 Number of primitives forwarded to the rasterizer.
370 Number of primitives rasterized.
371 Number of fragment shader threads launched.
372 Number of tessellation control shader threads launched.
373 Number of tessellation evaluation shader threads launched.
374 If a shader type is not supported by the device/driver,
375 the corresponding values should be set to 0.
377 Gallium does not guarantee the availability of any query types; one must
378 always check the capabilities of the :ref:`Screen` first.
381 Conditional Rendering
382 ^^^^^^^^^^^^^^^^^^^^^
384 A drawing command can be skipped depending on the outcome of a query
385 (typically an occlusion query, or streamout overflow predicate).
386 The ``render_condition`` function specifies the query which should be checked
387 prior to rendering anything. Functions honoring render_condition include
388 (and are limited to) draw_vbo, clear, clear_render_target, clear_depth_stencil.
390 If ``render_condition`` is called with ``query`` = NULL, conditional
391 rendering is disabled and drawing takes place normally.
393 If ``render_condition`` is called with a non-null ``query`` subsequent
394 drawing commands will be predicated on the outcome of the query.
395 Commands will be skipped if ``condition`` is equal to the predicate result
396 (for non-boolean queries such as OCCLUSION_QUERY, zero counts as FALSE,
399 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
400 query to complete before deciding whether to render.
402 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
403 completed, the drawing command will be executed normally. If the query
404 has completed, drawing will be predicated on the outcome of the query.
406 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
407 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
408 for the non-REGION modes but in the case that an occlusion query returns
409 a non-zero result, regions which were occluded may be ommitted by subsequent
410 drawing commands. This can result in better performance with some GPUs.
411 Normally, if the occlusion query returned a non-zero result subsequent
412 drawing happens normally so fragments may be generated, shaded and
413 processed even where they're known to be obscured.
422 Resource Busy Queries
423 ^^^^^^^^^^^^^^^^^^^^^
425 ``is_resource_referenced``
432 These methods emulate classic blitter controls.
434 These methods operate directly on ``pipe_resource`` objects, and stand
435 apart from any 3D state in the context. Blitting functionality may be
436 moved to a separate abstraction at some point in the future.
438 ``resource_copy_region`` blits a region of a resource to a region of another
439 resource, provided that both resources have the same format, or compatible
440 formats, i.e., formats for which copying the bytes from the source resource
441 unmodified to the destination resource will achieve the same effect of a
442 textured quad blitter.. The source and destination may be the same resource,
443 but overlapping blits are not permitted.
444 This can be considered the equivalent of a CPU memcpy.
446 ``blit`` blits a region of a resource to a region of another resource, including
447 scaling, format conversion, and up-/downsampling, as well as
448 a destination clip rectangle (scissors).
449 As opposed to manually drawing a textured quad, this lets the pipe driver choose
450 the optimal method for blitting (like using a special 2D engine), and usually
451 offers, for example, accelerated stencil-only copies even where
452 PIPE_CAP_SHADER_STENCIL_EXPORT is not available.
458 These methods are used to get data to/from a resource.
460 ``transfer_map`` creates a memory mapping and the transfer object
462 The returned pointer points to the start of the mapped range according to
463 the box region, not the beginning of the resource. If transfer_map fails,
464 the returned pointer to the buffer memory is NULL, and the pointer
465 to the transfer object remains unchanged (i.e. it can be non-NULL).
467 ``transfer_unmap`` remove the memory mapping for and destroy
468 the transfer object. The pointer into the resource should be considered
469 invalid and discarded.
471 ``transfer_inline_write`` performs a simplified transfer for simple writes.
472 Basically transfer_map, data write, and transfer_unmap all in one.
475 The box parameter to some of these functions defines a 1D, 2D or 3D
476 region of pixels. This is self-explanatory for 1D, 2D and 3D texture
479 For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth
480 fields refer to the array dimension of the texture.
482 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
483 faces of the cube map (z + depth <= 6).
485 For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both
486 the face and array dimension of the texture (face = z % 6, array = z / 6).
489 .. _transfer_flush_region:
491 transfer_flush_region
492 %%%%%%%%%%%%%%%%%%%%%
494 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
495 be flushed on write or unmap. Flushes must be requested with
496 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
497 the beginning of the resource.
506 This function flushes all pending writes to the currently-set surfaces and
507 invalidates all read caches of the currently-set samplers.
516 These flags control the behavior of a transfer object.
518 ``PIPE_TRANSFER_READ``
519 Resource contents read back (or accessed directly) at transfer create time.
521 ``PIPE_TRANSFER_WRITE``
522 Resource contents will be written back at transfer_unmap time (or modified
523 as a result of being accessed directly).
525 ``PIPE_TRANSFER_MAP_DIRECTLY``
526 a transfer should directly map the resource. May return NULL if not supported.
528 ``PIPE_TRANSFER_DISCARD_RANGE``
529 The memory within the mapped region is discarded. Cannot be used with
530 ``PIPE_TRANSFER_READ``.
532 ``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE``
533 Discards all memory backing the resource. It should not be used with
534 ``PIPE_TRANSFER_READ``.
536 ``PIPE_TRANSFER_DONTBLOCK``
537 Fail if the resource cannot be mapped immediately.
539 ``PIPE_TRANSFER_UNSYNCHRONIZED``
540 Do not synchronize pending operations on the resource when mapping. The
541 interaction of any writes to the map and any operations pending on the
542 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``.
544 ``PIPE_TRANSFER_FLUSH_EXPLICIT``
545 Written ranges will be notified later with :ref:`transfer_flush_region`.
546 Cannot be used with ``PIPE_TRANSFER_READ``.
549 Compute kernel execution
550 ^^^^^^^^^^^^^^^^^^^^^^^^
552 A compute program can be defined, bound or destroyed using
553 ``create_compute_state``, ``bind_compute_state`` or
554 ``destroy_compute_state`` respectively.
556 Any of the subroutines contained within the compute program can be
557 executed on the device using the ``launch_grid`` method. This method
558 will execute as many instances of the program as elements in the
559 specified N-dimensional grid, hopefully in parallel.
561 The compute program has access to four special resources:
563 * ``GLOBAL`` represents a memory space shared among all the threads
564 running on the device. An arbitrary buffer created with the
565 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the
566 ``set_global_binding`` method.
568 * ``LOCAL`` represents a memory space shared among all the threads
569 running in the same working group. The initial contents of this
570 resource are undefined.
572 * ``PRIVATE`` represents a memory space local to a single thread.
573 The initial contents of this resource are undefined.
575 * ``INPUT`` represents a read-only memory space that can be
576 initialized at ``launch_grid`` time.
578 These resources use a byte-based addressing scheme, and they can be
579 accessed from the compute program by means of the LOAD/STORE TGSI
580 opcodes. Additional resources to be accessed using the same opcodes
581 may be specified by the user with the ``set_compute_resources``
584 In addition, normal texture sampling is allowed from the compute
585 program: ``bind_compute_sampler_states`` may be used to set up texture
586 samplers for the compute stage and ``set_compute_sampler_views`` may
587 be used to bind a number of sampler views to it.