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). The ``render_condition`` function specifies
386 the query which should be checked prior to rendering anything.
388 If ``render_condition`` is called with ``query`` = NULL, conditional
389 rendering is disabled and drawing takes place normally.
391 If ``render_condition`` is called with a non-null ``query`` subsequent
392 drawing commands will be predicated on the outcome of the query. If
393 the query result is zero subsequent drawing commands will be skipped.
395 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
396 query to complete before deciding whether to render.
398 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
399 completed, the drawing command will be executed normally. If the query
400 has completed, drawing will be predicated on the outcome of the query.
402 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
403 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
404 for the non-REGION modes but in the case that an occulusion query returns
405 a non-zero result, regions which were occluded may be ommitted by subsequent
406 drawing commands. This can result in better performance with some GPUs.
407 Normally, if the occlusion query returned a non-zero result subsequent
408 drawing happens normally so fragments may be generated, shaded and
409 processed even where they're known to be obscured.
418 Resource Busy Queries
419 ^^^^^^^^^^^^^^^^^^^^^
421 ``is_resource_referenced``
428 These methods emulate classic blitter controls.
430 These methods operate directly on ``pipe_resource`` objects, and stand
431 apart from any 3D state in the context. Blitting functionality may be
432 moved to a separate abstraction at some point in the future.
434 ``resource_copy_region`` blits a region of a resource to a region of another
435 resource, provided that both resources have the same format, or compatible
436 formats, i.e., formats for which copying the bytes from the source resource
437 unmodified to the destination resource will achieve the same effect of a
438 textured quad blitter.. The source and destination may be the same resource,
439 but overlapping blits are not permitted.
440 This can be considered the equivalent of a CPU memcpy.
442 ``blit`` blits a region of a resource to a region of another resource, including
443 scaling, format conversion, and up-/downsampling, as well as
444 a destination clip rectangle (scissors).
445 As opposed to manually drawing a textured quad, this lets the pipe driver choose
446 the optimal method for blitting (like using a special 2D engine), and usually
447 offers, for example, accelerated stencil-only copies even where
448 PIPE_CAP_SHADER_STENCIL_EXPORT is not available.
454 These methods are used to get data to/from a resource.
456 ``transfer_map`` creates a memory mapping and the transfer object
458 The returned pointer points to the start of the mapped range according to
459 the box region, not the beginning of the resource. If transfer_map fails,
460 the returned pointer to the buffer memory is NULL, and the pointer
461 to the transfer object remains unchanged (i.e. it can be non-NULL).
463 ``transfer_unmap`` remove the memory mapping for and destroy
464 the transfer object. The pointer into the resource should be considered
465 invalid and discarded.
467 ``transfer_inline_write`` performs a simplified transfer for simple writes.
468 Basically transfer_map, data write, and transfer_unmap all in one.
471 The box parameter to some of these functions defines a 1D, 2D or 3D
472 region of pixels. This is self-explanatory for 1D, 2D and 3D texture
475 For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth
476 fields refer to the array dimension of the texture.
478 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
479 faces of the cube map (z + depth <= 6).
481 For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both
482 the face and array dimension of the texture (face = z % 6, array = z / 6).
485 .. _transfer_flush_region:
487 transfer_flush_region
488 %%%%%%%%%%%%%%%%%%%%%
490 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
491 be flushed on write or unmap. Flushes must be requested with
492 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
493 the beginning of the resource.
502 This function flushes all pending writes to the currently-set surfaces and
503 invalidates all read caches of the currently-set samplers.
512 These flags control the behavior of a transfer object.
514 ``PIPE_TRANSFER_READ``
515 Resource contents read back (or accessed directly) at transfer create time.
517 ``PIPE_TRANSFER_WRITE``
518 Resource contents will be written back at transfer_unmap time (or modified
519 as a result of being accessed directly).
521 ``PIPE_TRANSFER_MAP_DIRECTLY``
522 a transfer should directly map the resource. May return NULL if not supported.
524 ``PIPE_TRANSFER_DISCARD_RANGE``
525 The memory within the mapped region is discarded. Cannot be used with
526 ``PIPE_TRANSFER_READ``.
528 ``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE``
529 Discards all memory backing the resource. It should not be used with
530 ``PIPE_TRANSFER_READ``.
532 ``PIPE_TRANSFER_DONTBLOCK``
533 Fail if the resource cannot be mapped immediately.
535 ``PIPE_TRANSFER_UNSYNCHRONIZED``
536 Do not synchronize pending operations on the resource when mapping. The
537 interaction of any writes to the map and any operations pending on the
538 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``.
540 ``PIPE_TRANSFER_FLUSH_EXPLICIT``
541 Written ranges will be notified later with :ref:`transfer_flush_region`.
542 Cannot be used with ``PIPE_TRANSFER_READ``.
545 Compute kernel execution
546 ^^^^^^^^^^^^^^^^^^^^^^^^
548 A compute program can be defined, bound or destroyed using
549 ``create_compute_state``, ``bind_compute_state`` or
550 ``destroy_compute_state`` respectively.
552 Any of the subroutines contained within the compute program can be
553 executed on the device using the ``launch_grid`` method. This method
554 will execute as many instances of the program as elements in the
555 specified N-dimensional grid, hopefully in parallel.
557 The compute program has access to four special resources:
559 * ``GLOBAL`` represents a memory space shared among all the threads
560 running on the device. An arbitrary buffer created with the
561 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the
562 ``set_global_binding`` method.
564 * ``LOCAL`` represents a memory space shared among all the threads
565 running in the same working group. The initial contents of this
566 resource are undefined.
568 * ``PRIVATE`` represents a memory space local to a single thread.
569 The initial contents of this resource are undefined.
571 * ``INPUT`` represents a read-only memory space that can be
572 initialized at ``launch_grid`` time.
574 These resources use a byte-based addressing scheme, and they can be
575 accessed from the compute program by means of the LOAD/STORE TGSI
576 opcodes. Additional resources to be accessed using the same opcodes
577 may be specified by the user with the ``set_compute_resources``
580 In addition, normal texture sampling is allowed from the compute
581 program: ``bind_compute_sampler_states`` may be used to set up texture
582 samplers for the compute stage and ``set_compute_sampler_views`` may
583 be used to bind a number of sampler views to it.