4 The context object represents the purest, most directly accessible, abilities
5 of the device's 3D rendering pipeline.
13 All CSO state is created, bound, and destroyed, with triplets of methods that
14 all follow a specific naming scheme. For example, ``create_blend_state``,
15 ``bind_blend_state``, and ``destroy_blend_state``.
17 CSO objects handled by the context object:
19 * :ref:`Blend`: ``*_blend_state``
20 * :ref:`Sampler`: These are special; they can be bound to either vertex or
21 fragment samplers, and they are bound in groups.
22 ``bind_fragment_sampler_states``, ``bind_vertex_sampler_states``
23 * :ref:`Rasterizer`: ``*_rasterizer_state``
24 * :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state``
25 * :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for
26 fragment shaders, and ``*_vs_state`` is for vertex shaders.
27 * :ref:`Vertex Elements`: ``*_vertex_elements_state``
30 Resource Binding State
31 ^^^^^^^^^^^^^^^^^^^^^^
33 This state describes how resources in various flavours (textures,
34 buffers, surfaces) are bound to the driver.
37 * ``set_constant_buffer`` sets a constant buffer to be used for a given shader
38 type. index is used to indicate which buffer to set (some apis may allow
39 multiple ones to be set, and binding a specific one later, though drivers
40 are mostly restricted to the first one right now).
42 * ``set_framebuffer_state``
44 * ``set_vertex_buffers``
50 These pieces of state are too small, variable, and/or trivial to have CSO
51 objects. They all follow simple, one-method binding calls, e.g.
54 * ``set_stencil_ref`` sets the stencil front and back reference values
55 which are used as comparison values in stencil test.
58 * ``set_polygon_stipple``
59 * ``set_scissor_state`` sets the bounds for the scissor test, which culls
60 pixels before blending to render targets. If the :ref:`Rasterizer` does
61 not have the scissor test enabled, then the scissor bounds never need to
62 be set since they will not be used.
63 * ``set_viewport_state``
69 These are the means to bind textures to shader stages. To create one, specify
70 its format, swizzle and LOD range in sampler view template.
72 If texture format is different than template format, it is said the texture
73 is being cast to another format. Casting can be done only between compatible
74 formats, that is formats that have matching component order and sizes.
76 Swizzle fields specify they way in which fetched texel components are placed
77 in the result register. For example, ``swizzle_r`` specifies what is going to be
78 placed in first component of result register.
80 The ``first_level`` and ``last_level`` fields of sampler view template specify
81 the LOD range the texture is going to be constrained to.
83 * ``set_fragment_sampler_views`` binds an array of sampler views to
84 fragment shader stage. Every binding point acquires a reference
85 to a respective sampler view and releases a reference to the previous
88 * ``set_vertex_sampler_views`` binds an array of sampler views to vertex
89 shader stage. Every binding point acquires a reference to a respective
90 sampler view and releases a reference to the previous sampler view.
92 * ``create_sampler_view`` creates a new sampler view. ``texture`` is associated
93 with the sampler view which results in sampler view holding a reference
94 to the texture. Format specified in template must be compatible
97 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
98 to associated texture.
104 ``clear`` initializes some or all of the surfaces currently bound to
105 the framebuffer to particular RGBA, depth, or stencil values.
107 Clear is one of the most difficult concepts to nail down to a single
108 interface and it seems likely that we will want to add additional
109 clear paths, for instance clearing surfaces not bound to the
110 framebuffer, or read-modify-write clears such as depth-only or
111 stencil-only clears of packed depth-stencil buffers.
117 ``draw_arrays`` draws a specified primitive.
119 This command is equivalent to calling ``draw_arrays_instanced``
120 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
122 ``draw_elements`` draws a specified primitive using an optional
125 This command is equivalent to calling ``draw_elements_instanced``
126 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
128 ``draw_range_elements``
130 XXX: this is (probably) a temporary entrypoint, as the range
131 information should be available from the vertex_buffer state.
132 Using this to quickly evaluate a specialized path in the draw
135 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
137 This command is equivalent to calling ``draw_elements_instanced``
138 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
140 ``draw_elements_instanced`` draws multiple instances of the same primitive
141 using an optional index buffer.
143 For instanceID in the range between ``startInstance``
144 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
145 specified by ``mode`` and sequential numbers in the range between ``start``
146 and ``start``+``count``-1, inclusive.
148 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
149 byte size of ``indexSize``. The sequential numbers are used to lookup
150 the index buffer and the resulting indices in turn are used to fetch
153 If ``indexBuffer`` is NULL, the sequential numbers are used directly
154 as indices to fetch vertex attributes.
156 ``indexBias`` is a value which is added to every index read from the index
157 buffer before fetching vertex attributes.
159 ``minIndex`` and ``maxIndex`` describe minimum and maximum index contained in
162 If a given vertex element has ``instance_divisor`` set to 0, it is said
163 it contains per-vertex data and effective vertex attribute address needs
164 to be recalculated for every index.
166 attribAddr = ``stride`` * index + ``src_offset``
168 If a given vertex element has ``instance_divisor`` set to non-zero,
169 it is said it contains per-instance data and effective vertex attribute
170 address needs to recalculated for every ``instance_divisor``-th instance.
172 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
174 In the above formulas, ``src_offset`` is taken from the given vertex element
175 and ``stride`` is taken from a vertex buffer associated with the given
178 The calculated attribAddr is used as an offset into the vertex buffer to
179 fetch the attribute data.
181 The value of ``instanceID`` can be read in a vertex shader through a system
182 value register declared with INSTANCEID semantic name.
188 Queries gather some statistic from the 3D pipeline over one or more
189 draws. Queries may be nested, though no state tracker currently
192 Queries can be created with ``create_query`` and deleted with
193 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
194 use ``end_query`` to end the query.
196 ``get_query_result`` is used to retrieve the results of a query. If
197 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
198 will block until the results of the query are ready (and TRUE will be
199 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
200 will not block and the return value will be TRUE if the query has
201 completed or FALSE otherwise.
203 A common type of query is the occlusion query which counts the number of
204 fragments/pixels which are written to the framebuffer (and not culled by
205 Z/stencil/alpha testing or shader KILL instructions).
208 Conditional Rendering
209 ^^^^^^^^^^^^^^^^^^^^^
211 A drawing command can be skipped depending on the outcome of a query
212 (typically an occlusion query). The ``render_condition`` function specifies
213 the query which should be checked prior to rendering anything.
215 If ``render_condition`` is called with ``query`` = NULL, conditional
216 rendering is disabled and drawing takes place normally.
218 If ``render_condition`` is called with a non-null ``query`` subsequent
219 drawing commands will be predicated on the outcome of the query. If
220 the query result is zero subsequent drawing commands will be skipped.
222 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
223 query to complete before deciding whether to render.
225 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
226 completed, the drawing command will be executed normally. If the query
227 has completed, drawing will be predicated on the outcome of the query.
229 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
230 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
231 for the non-REGION modes but in the case that an occulusion query returns
232 a non-zero result, regions which were occluded may be ommitted by subsequent
233 drawing commands. This can result in better performance with some GPUs.
234 Normally, if the occlusion query returned a non-zero result subsequent
235 drawing happens normally so fragments may be generated, shaded and
236 processed even where they're known to be obscured.
245 Resource Busy Queries
246 ^^^^^^^^^^^^^^^^^^^^^
248 ``is_resource_referenced``
255 These methods emulate classic blitter controls. They are not guaranteed to be
256 available; if they are set to NULL, then they are not present.
258 These methods operate directly on ``pipe_surface`` objects, and stand
259 apart from any 3D state in the context. Blitting functionality may be
260 moved to a separate abstraction at some point in the future.
262 ``surface_fill`` performs a fill operation on a section of a surface.
264 ``surface_copy`` blits a region of a surface to a region of another surface,
265 provided that both surfaces are the same format. The source and destination
266 may be the same surface, and overlapping blits are permitted.
268 The interfaces to these calls are likely to change to make it easier
269 for a driver to batch multiple blits with the same source and
276 These methods are used to get data to/from a resource.
278 ``get_transfer`` creates a transfer object.
280 ``transfer_destroy`` destroys the transfer object. May cause
281 data to be written to the resource at this point.
283 ``transfer_map`` creates a memory mapping for the transfer object.
284 The returned map points to the start of the mapped range according to
285 the box region, not the beginning of the resource.
287 .. _transfer_flush_region:
288 ``transfer_flush_region`` If a transfer was created with TRANFER_FLUSH_EXPLICIT,
289 only the region specified is guaranteed to be written to. This is relative to
290 the mapped range, not the beginning of the resource.
292 ``transfer_unmap`` remove the memory mapping for the transfer object.
293 Any pointers into the map should be considered invalid and discarded.
295 ``transfer_inline_write`` performs a simplified transfer for simple writes.
296 Basically get_transfer, transfer_map, data write, transfer_unmap, and
297 transfer_destroy all in one.
304 These flags control the behavior of a transfer object.
306 * ``READ``: resource contents are read at transfer create time.
307 * ``WRITE``: resource contents will be written back at transfer destroy time.
308 * ``MAP_DIRECTLY``: a transfer should directly map the resource. May return
309 NULL if not supported.
310 * ``DISCARD``: The memory within the mapped region is discarded.
311 Cannot be used with ``READ``.
312 * ``DONTBLOCK``: Fail if the resource cannot be mapped immediately.
313 * ``UNSYNCHRONIZED``: Do not synchronize pending operations on the resource
314 when mapping. The interaction of any writes to the map and any
315 operations pending on the resource are undefined. Cannot be used with
317 * ``FLUSH_EXPLICIT``: Written ranges will be notified later with
318 :ref:`transfer_flush_region`. Cannot be used with