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.
29 Resource Binding State
30 ^^^^^^^^^^^^^^^^^^^^^^
32 This state describes how resources in various flavours (textures,
33 buffers, surfaces) are bound to the driver.
36 * ``set_constant_buffer`` sets a constant buffer to be used for a given shader
37 type. index is used to indicate which buffer to set (some apis may allow
38 multiple ones to be set, and binding a specific one later, though drivers
39 are mostly restricted to the first one right now).
41 * ``set_framebuffer_state``
42 * ``set_fragment_sampler_textures``
43 * ``set_vertex_sampler_textures``
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.
56 * ``set_polygon_stipple``
57 * ``set_scissor_state`` sets the bounds for the scissor test, which culls
58 pixels before blending to render targets. If the :ref:`Rasterizer` does
59 not have the scissor test enabled, then the scissor bounds never need to
60 be set since they will not be used.
61 * ``set_viewport_state``
62 * ``set_vertex_elements``
68 ``clear`` initializes some or all of the surfaces currently bound to
69 the framebuffer to particular RGBA, depth, or stencil values.
71 Clear is one of the most difficult concepts to nail down to a single
72 interface and it seems likely that we will want to add additional
73 clear paths, for instance clearing surfaces not bound to the
74 framebuffer, or read-modify-write clears such as depth-only or
75 stencil-only clears of packed depth-stencil buffers.
81 ``draw_arrays`` draws a specified primitive.
83 This command is equivalent to calling ``draw_arrays_instanced``
84 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
86 ``draw_elements`` draws a specified primitive using an optional
89 This command is equivalent to calling ``draw_elements_instanced``
90 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
92 ``draw_range_elements``
94 XXX: this is (probably) a temporary entrypoint, as the range
95 information should be available from the vertex_buffer state.
96 Using this to quickly evaluate a specialized path in the draw
99 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
101 This command is equivalent to calling ``draw_elements_instanced``
102 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
104 ``draw_elements_instanced`` draws multiple instances of the same primitive
105 using an optional index buffer.
107 For instanceID in the range between ``startInstance``
108 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
109 specified by ``mode`` and sequential numbers in the range between ``start``
110 and ``start``+``count``-1, inclusive.
112 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
113 byte size of ``indexSize``. The sequential numbers are used to lookup
114 the index buffer and the resulting indices in turn are used to fetch
117 If ``indexBuffer`` is NULL, the sequential numbers are used directly
118 as indices to fetch vertex attributes.
120 If a given vertex element has ``instance_divisor`` set to 0, it is said
121 it contains per-vertex data and effective vertex attribute address needs
122 to be recalculated for every index.
124 attribAddr = ``stride`` * index + ``src_offset``
126 If a given vertex element has ``instance_divisor`` set to non-zero,
127 it is said it contains per-instance data and effective vertex attribute
128 address needs to recalculated for every ``instance_divisor``-th instance.
130 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
132 In the above formulas, ``src_offset`` is taken from the given vertex element
133 and ``stride`` is taken from a vertex buffer associated with the given
136 The calculated attribAddr is used as an offset into the vertex buffer to
137 fetch the attribute data.
139 The value of ``instanceID`` can be read in a vertex shader through a system
140 value register declared with INSTANCEID semantic name.
146 Queries gather some statistic from the 3D pipeline over one or more
147 draws. Queries may be nested, though no state tracker currently
150 Queries can be created with ``create_query`` and deleted with
151 ``destroy_query``. To enable a query, use ``begin_query``, and when finished,
152 use ``end_query`` to stop the query. Finally, ``get_query_result`` is used
153 to retrieve the results.
155 A common type of query is the occlusion query which counts the number of
156 fragments/pixels which are written to the framebuffer (and not culled by
157 Z/stencil/alpha testing or shader KILL instructions).
160 Conditional Rendering
161 ^^^^^^^^^^^^^^^^^^^^^
163 A drawing command can be skipped depending on the outcome of a query
164 (typically an occlusion query). The ``render_condition`` function specifies
165 the query which should be checked prior to rendering anything.
167 If ``render_condition`` is called with ``query`` = NULL, conditional
168 rendering is disabled and drawing takes place normally.
170 If ``render_condition`` is called with a non-null ``query`` subsequent
171 drawing commands will be predicated on the outcome of the query. If
172 the query result is zero subsequent drawing commands will be skipped.
174 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
175 query to complete before deciding whether to render.
177 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
178 completed, the drawing command will be executed normally. If the query
179 has completed, drawing will be predicated on the outcome of the query.
181 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
182 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
183 for the non-REGION modes but in the case that an occulusion query returns
184 a non-zero result, regions which were occluded may be ommitted by subsequent
185 drawing commands. This can result in better performance with some GPUs.
186 Normally, if the occlusion query returned a non-zero result subsequent
187 drawing happens normally so fragments may be generated, shaded and
188 processed even where they're known to be obscured.
197 Resource Busy Queries
198 ^^^^^^^^^^^^^^^^^^^^^
200 ``is_texture_referenced``
202 ``is_buffer_referenced``
209 These methods emulate classic blitter controls. They are not guaranteed to be
210 available; if they are set to NULL, then they are not present.
212 These methods operate directly on ``pipe_surface`` objects, and stand
213 apart from any 3D state in the context. Blitting functionality may be
214 moved to a separate abstraction at some point in the future.
216 ``surface_fill`` performs a fill operation on a section of a surface.
218 ``surface_copy`` blits a region of a surface to a region of another surface,
219 provided that both surfaces are the same format. The source and destination
220 may be the same surface, and overlapping blits are permitted.
222 The interfaces to these calls are likely to change to make it easier
223 for a driver to batch multiple blits with the same source and