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_fragment_sampler_views`` binds an array of sampler views to
45 fragment shader stage. Every binding point acquires a reference
46 to a respective sampler view and releases a reference to the previous
49 * ``set_vertex_sampler_views`` binds an array of sampler views to vertex
50 shader stage. Every binding point acquires a reference to a respective
51 sampler view and releases a reference to the previous sampler view.
53 * ``create_sampler_view`` creates a new sampler view. texture is associated
54 with the sampler view which results in sampler view holding a reference
55 to the texture. Format specified in template must be compatible
58 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
59 to associated texture.
61 * ``set_vertex_buffers``
67 These pieces of state are too small, variable, and/or trivial to have CSO
68 objects. They all follow simple, one-method binding calls, e.g.
70 * ``set_stencil_ref`` sets the stencil front and back reference values
71 which are used as comparison values in stencil test.
74 * ``set_polygon_stipple``
75 * ``set_scissor_state`` sets the bounds for the scissor test, which culls
76 pixels before blending to render targets. If the :ref:`Rasterizer` does
77 not have the scissor test enabled, then the scissor bounds never need to
78 be set since they will not be used.
79 * ``set_viewport_state``
85 ``clear`` initializes some or all of the surfaces currently bound to
86 the framebuffer to particular RGBA, depth, or stencil values.
88 Clear is one of the most difficult concepts to nail down to a single
89 interface and it seems likely that we will want to add additional
90 clear paths, for instance clearing surfaces not bound to the
91 framebuffer, or read-modify-write clears such as depth-only or
92 stencil-only clears of packed depth-stencil buffers.
98 ``draw_arrays`` draws a specified primitive.
100 This command is equivalent to calling ``draw_arrays_instanced``
101 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
103 ``draw_elements`` draws a specified primitive using an optional
106 This command is equivalent to calling ``draw_elements_instanced``
107 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
109 ``draw_range_elements``
111 XXX: this is (probably) a temporary entrypoint, as the range
112 information should be available from the vertex_buffer state.
113 Using this to quickly evaluate a specialized path in the draw
116 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
118 This command is equivalent to calling ``draw_elements_instanced``
119 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
121 ``draw_elements_instanced`` draws multiple instances of the same primitive
122 using an optional index buffer.
124 For instanceID in the range between ``startInstance``
125 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
126 specified by ``mode`` and sequential numbers in the range between ``start``
127 and ``start``+``count``-1, inclusive.
129 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
130 byte size of ``indexSize``. The sequential numbers are used to lookup
131 the index buffer and the resulting indices in turn are used to fetch
134 If ``indexBuffer`` is NULL, the sequential numbers are used directly
135 as indices to fetch vertex attributes.
137 If a given vertex element has ``instance_divisor`` set to 0, it is said
138 it contains per-vertex data and effective vertex attribute address needs
139 to be recalculated for every index.
141 attribAddr = ``stride`` * index + ``src_offset``
143 If a given vertex element has ``instance_divisor`` set to non-zero,
144 it is said it contains per-instance data and effective vertex attribute
145 address needs to recalculated for every ``instance_divisor``-th instance.
147 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
149 In the above formulas, ``src_offset`` is taken from the given vertex element
150 and ``stride`` is taken from a vertex buffer associated with the given
153 The calculated attribAddr is used as an offset into the vertex buffer to
154 fetch the attribute data.
156 The value of ``instanceID`` can be read in a vertex shader through a system
157 value register declared with INSTANCEID semantic name.
163 Queries gather some statistic from the 3D pipeline over one or more
164 draws. Queries may be nested, though no state tracker currently
167 Queries can be created with ``create_query`` and deleted with
168 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
169 use ``end_query`` to end the query.
171 ``get_query_result`` is used to retrieve the results of a query. If
172 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
173 will block until the results of the query are ready (and TRUE will be
174 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
175 will not block and the return value will be TRUE if the query has
176 completed or FALSE otherwise.
178 A common type of query is the occlusion query which counts the number of
179 fragments/pixels which are written to the framebuffer (and not culled by
180 Z/stencil/alpha testing or shader KILL instructions).
183 Conditional Rendering
184 ^^^^^^^^^^^^^^^^^^^^^
186 A drawing command can be skipped depending on the outcome of a query
187 (typically an occlusion query). The ``render_condition`` function specifies
188 the query which should be checked prior to rendering anything.
190 If ``render_condition`` is called with ``query`` = NULL, conditional
191 rendering is disabled and drawing takes place normally.
193 If ``render_condition`` is called with a non-null ``query`` subsequent
194 drawing commands will be predicated on the outcome of the query. If
195 the query result is zero subsequent drawing commands will be skipped.
197 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
198 query to complete before deciding whether to render.
200 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
201 completed, the drawing command will be executed normally. If the query
202 has completed, drawing will be predicated on the outcome of the query.
204 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
205 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
206 for the non-REGION modes but in the case that an occulusion query returns
207 a non-zero result, regions which were occluded may be ommitted by subsequent
208 drawing commands. This can result in better performance with some GPUs.
209 Normally, if the occlusion query returned a non-zero result subsequent
210 drawing happens normally so fragments may be generated, shaded and
211 processed even where they're known to be obscured.
220 Resource Busy Queries
221 ^^^^^^^^^^^^^^^^^^^^^
223 ``is_texture_referenced``
225 ``is_buffer_referenced``
232 These methods emulate classic blitter controls. They are not guaranteed to be
233 available; if they are set to NULL, then they are not present.
235 These methods operate directly on ``pipe_surface`` objects, and stand
236 apart from any 3D state in the context. Blitting functionality may be
237 moved to a separate abstraction at some point in the future.
239 ``surface_fill`` performs a fill operation on a section of a surface.
241 ``surface_copy`` blits a region of a surface to a region of another surface,
242 provided that both surfaces are the same format. The source and destination
243 may be the same surface, and overlapping blits are permitted.
245 The interfaces to these calls are likely to change to make it easier
246 for a driver to batch multiple blits with the same source and