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``
57 * ``set_stream_output_buffers``
63 These pieces of state are too small, variable, and/or trivial to have CSO
64 objects. They all follow simple, one-method binding calls, e.g.
67 * ``set_stencil_ref`` sets the stencil front and back reference values
68 which are used as comparison values in stencil test.
72 * ``set_polygon_stipple``
73 * ``set_scissor_state`` 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].
79 * ``set_viewport_state``
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 These are the means to use resources as color render targets or depthstencil
129 attachments. To create one, specify the mip level, the range of layers, and
130 the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
131 Note that layer values are in addition to what is indicated by the geometry
132 shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
133 shader indicates index 2, the 5th layer of the resource will be used). These
134 first_layer and last_layer parameters will only be used for 1d array, 2d array,
135 cube, and 3d textures otherwise they are 0.
137 * ``create_surface`` creates a new surface.
139 * ``surface_destroy`` destroys a surface and releases its reference to the
145 Clear is one of the most difficult concepts to nail down to a single
146 interface (due to both different requirements from APIs and also driver/hw
147 specific differences).
149 ``clear`` initializes some or all of the surfaces currently bound to
150 the framebuffer to particular RGBA, depth, or stencil values.
151 Currently, this does not take into account color or stencil write masks (as
152 used by GL), and always clears the whole surfaces (no scissoring as used by
153 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
154 only depth or stencil in a combined depth/stencil surface, if the driver
155 supports PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE.
156 If a surface includes several layers then all layers will be cleared.
158 ``clear_render_target`` clears a single color rendertarget with the specified
159 color value. While it is only possible to clear one surface at a time (which can
160 include several layers), this surface need not be bound to the framebuffer.
162 ``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface
163 with the specified depth and stencil values (for combined depth/stencil buffers,
164 is is also possible to only clear one or the other part). While it is only
165 possible to clear one surface at a time (which can include several layers),
166 this surface need not be bound to the framebuffer.
172 ``draw_vbo`` draws a specified primitive. The primitive mode and other
173 properties are described by ``pipe_draw_info``.
175 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the
176 the mode of the primitive and the vertices to be fetched, in the range between
177 ``start`` to ``start``+``count``-1, inclusive.
179 Every instance with instanceID in the range between ``start_instance`` and
180 ``start_instance``+``instance_count``-1, inclusive, will be drawn.
182 All vertex indices must fall inside the range given by ``min_index`` and
183 ``max_index``. In case non-indexed draw, ``min_index`` should be set to
184 ``start`` and ``max_index`` should be set to ``start``+``count``-1.
186 ``index_bias`` is a value added to every vertex index before fetching vertex
187 attributes. It does not affect ``min_index`` and ``max_index``.
189 If there is an index buffer bound, and ``indexed`` field is true, all vertex
190 indices will be looked up in the index buffer. ``min_index``, ``max_index``,
191 and ``index_bias`` apply after index lookup.
193 When drawing indexed primitives, the primitive restart index can be
194 used to draw disjoint primitive strips. For example, several separate
195 line strips can be drawn by designating a special index value as the
196 restart index. The ``primitive_restart`` flag enables/disables this
197 feature. The ``restart_index`` field specifies the restart index value.
199 When primitive restart is in use, array indexes are compared to the
200 restart index before adding the index_bias offset.
202 If a given vertex element has ``instance_divisor`` set to 0, it is said
203 it contains per-vertex data and effective vertex attribute address needs
204 to be recalculated for every index.
206 attribAddr = ``stride`` * index + ``src_offset``
208 If a given vertex element has ``instance_divisor`` set to non-zero,
209 it is said it contains per-instance data and effective vertex attribute
210 address needs to recalculated for every ``instance_divisor``-th instance.
212 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
214 In the above formulas, ``src_offset`` is taken from the given vertex element
215 and ``stride`` is taken from a vertex buffer associated with the given
218 The calculated attribAddr is used as an offset into the vertex buffer to
219 fetch the attribute data.
221 The value of ``instanceID`` can be read in a vertex shader through a system
222 value register declared with INSTANCEID semantic name.
228 Queries gather some statistic from the 3D pipeline over one or more
229 draws. Queries may be nested, though no state tracker currently
232 Queries can be created with ``create_query`` and deleted with
233 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
234 use ``end_query`` to end the query.
236 ``get_query_result`` is used to retrieve the results of a query. If
237 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
238 will block until the results of the query are ready (and TRUE will be
239 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
240 will not block and the return value will be TRUE if the query has
241 completed or FALSE otherwise.
243 The most common type of query is the occlusion query,
244 ``PIPE_QUERY_OCCLUSION_COUNTER``, which counts the number of fragments which
245 are written to the framebuffer without being culled by
246 :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
247 The result is an unsigned 64-bit integer.
248 In cases where a boolean result of an occlusion query is enough,
249 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
250 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
251 value of FALSE for cases where COUNTER would result in 0 and TRUE
254 Another type of query, ``PIPE_QUERY_TIME_ELAPSED``, returns the amount of
255 time, in nanoseconds, the context takes to perform operations.
256 The result is an unsigned 64-bit integer.
258 Gallium does not guarantee the availability of any query types; one must
259 always check the capabilities of the :ref:`Screen` first.
262 Conditional Rendering
263 ^^^^^^^^^^^^^^^^^^^^^
265 A drawing command can be skipped depending on the outcome of a query
266 (typically an occlusion query). The ``render_condition`` function specifies
267 the query which should be checked prior to rendering anything.
269 If ``render_condition`` is called with ``query`` = NULL, conditional
270 rendering is disabled and drawing takes place normally.
272 If ``render_condition`` is called with a non-null ``query`` subsequent
273 drawing commands will be predicated on the outcome of the query. If
274 the query result is zero subsequent drawing commands will be skipped.
276 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
277 query to complete before deciding whether to render.
279 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
280 completed, the drawing command will be executed normally. If the query
281 has completed, drawing will be predicated on the outcome of the query.
283 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
284 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
285 for the non-REGION modes but in the case that an occulusion query returns
286 a non-zero result, regions which were occluded may be ommitted by subsequent
287 drawing commands. This can result in better performance with some GPUs.
288 Normally, if the occlusion query returned a non-zero result subsequent
289 drawing happens normally so fragments may be generated, shaded and
290 processed even where they're known to be obscured.
299 Resource Busy Queries
300 ^^^^^^^^^^^^^^^^^^^^^
302 ``is_resource_referenced``
309 These methods emulate classic blitter controls.
311 These methods operate directly on ``pipe_resource`` objects, and stand
312 apart from any 3D state in the context. Blitting functionality may be
313 moved to a separate abstraction at some point in the future.
315 ``resource_copy_region`` blits a region of a resource to a region of another
316 resource, provided that both resources have the same format, or compatible
317 formats, i.e., formats for which copying the bytes from the source resource
318 unmodified to the destination resource will achieve the same effect of a
319 textured quad blitter.. The source and destination may be the same resource,
320 but overlapping blits are not permitted.
322 ``resource_resolve`` resolves a multisampled resource into a non-multisampled
323 one. Formats and dimensions must match. This function must be present if a driver
324 supports multisampling.
326 The interfaces to these calls are likely to change to make it easier
327 for a driver to batch multiple blits with the same source and
334 Stream output, also known as transform feedback allows writing the results of the
335 vertex pipeline (after the geometry shader or vertex shader if no geometry shader
336 is present) to be written to a buffer created with a ``PIPE_BIND_STREAM_OUTPUT``
339 First a stream output state needs to be created with the
340 ``create_stream_output_state`` call. It specific the details of what's being written,
341 to which buffer and with what kind of a writemask.
343 Then target buffers needs to be set with the call to ``set_stream_output_buffers``
344 which sets the buffers and the offsets from the start of those buffer to where
345 the data will be written to.
351 These methods are used to get data to/from a resource.
353 ``get_transfer`` creates a transfer object.
355 ``transfer_destroy`` destroys the transfer object. May cause
356 data to be written to the resource at this point.
358 ``transfer_map`` creates a memory mapping for the transfer object.
359 The returned map points to the start of the mapped range according to
360 the box region, not the beginning of the resource.
362 ``transfer_unmap`` remove the memory mapping for the transfer object.
363 Any pointers into the map should be considered invalid and discarded.
365 ``transfer_inline_write`` performs a simplified transfer for simple writes.
366 Basically get_transfer, transfer_map, data write, transfer_unmap, and
367 transfer_destroy all in one.
370 The box parameter to some of these functions defines a 1D, 2D or 3D
371 region of pixels. This is self-explanatory for 1D, 2D and 3D texture
374 For PIPE_TEXTURE_1D_ARRAY, the box::y and box::height fields refer to the
375 array dimension of the texture.
377 For PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth fields refer to the
378 array dimension of the texture.
380 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
381 faces of the cube map (z + depth <= 6).
385 .. _transfer_flush_region:
387 transfer_flush_region
388 %%%%%%%%%%%%%%%%%%%%%
390 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
391 be flushed on write or unmap. Flushes must be requested with
392 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
393 the beginning of the resource.
397 .. _redefine_user_buffer:
402 This function notifies a driver that the user buffer content has been changed.
403 The updated region starts at ``offset`` and is ``size`` bytes large.
404 The ``offset`` is relative to the pointer specified in ``user_buffer_create``.
405 While uploading the user buffer, the driver is allowed not to upload
406 the memory outside of this region.
407 The width0 is redefined to ``MAX2(width0, offset+size)``.
416 These flags control the behavior of a transfer object.
418 ``PIPE_TRANSFER_READ``
419 Resource contents read back (or accessed directly) at transfer create time.
421 ``PIPE_TRANSFER_WRITE``
422 Resource contents will be written back at transfer_destroy time (or modified
423 as a result of being accessed directly).
425 ``PIPE_TRANSFER_MAP_DIRECTLY``
426 a transfer should directly map the resource. May return NULL if not supported.
428 ``PIPE_TRANSFER_DISCARD_RANGE``
429 The memory within the mapped region is discarded. Cannot be used with
430 ``PIPE_TRANSFER_READ``.
432 ``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE``
433 Discards all memory backing the resource. It should not be used with
434 ``PIPE_TRANSFER_READ``.
436 ``PIPE_TRANSFER_DONTBLOCK``
437 Fail if the resource cannot be mapped immediately.
439 ``PIPE_TRANSFER_UNSYNCHRONIZED``
440 Do not synchronize pending operations on the resource when mapping. The
441 interaction of any writes to the map and any operations pending on the
442 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``.
444 ``PIPE_TRANSFER_FLUSH_EXPLICIT``
445 Written ranges will be notified later with :ref:`transfer_flush_region`.
446 Cannot be used with ``PIPE_TRANSFER_READ``.