Context ======= The context object represents the purest, most directly accessible, abilities of the device's 3D rendering pipeline. Methods ------- CSO State ^^^^^^^^^ All CSO state is created, bound, and destroyed, with triplets of methods that all follow a specific naming scheme. For example, ``create_blend_state``, ``bind_blend_state``, and ``destroy_blend_state``. CSO objects handled by the context object: * :ref:`Blend`: ``*_blend_state`` * :ref:`Sampler`: These are special; they can be bound to either vertex or fragment samplers, and they are bound in groups. ``bind_fragment_sampler_states``, ``bind_vertex_sampler_states`` * :ref:`Rasterizer`: ``*_rasterizer_state`` * :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state`` * :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for fragment shaders, and ``*_vs_state`` is for vertex shaders. Resource Binding State ^^^^^^^^^^^^^^^^^^^^^^ This state describes how resources in various flavours (textures, buffers, surfaces) are bound to the driver. * ``set_constant_buffer`` * ``set_framebuffer_state`` * ``set_fragment_sampler_textures`` * ``set_vertex_sampler_textures`` * ``set_vertex_buffers`` Non-CSO State ^^^^^^^^^^^^^ These pieces of state are too small, variable, and/or trivial to have CSO objects. They all follow simple, one-method binding calls, e.g. ``set_edgeflags``. * ``set_edgeflags`` * ``set_blend_color`` * ``set_clip_state`` * ``set_polygon_stipple`` * ``set_scissor_state`` * ``set_viewport_state`` * ``set_vertex_elements`` Clearing ^^^^^^^^ ``clear`` initializes some or all of the surfaces currently bound to the framebuffer to particular RGBA, depth, or stencil values. Clear is one of the most difficult concepts to nail down to a single interface and it seems likely that we will want to add additional clear paths, for instance clearing surfaces not bound to the framebuffer, or read-modify-write clears such as depth-only or stencil-only clears of packed depth-stencil buffers. Drawing ^^^^^^^ ``draw_arrays`` draws a specified primitive. This command is equivalent to calling ``draw_arrays_instanced`` with ``startInstance`` set to 0 and ``instanceCount`` set to 1. ``draw_elements`` draws a specified primitive using an optional index buffer. This command is equivalent to calling ``draw_elements_instanced`` with ``startInstance`` set to 0 and ``instanceCount`` set to 1. ``draw_range_elements`` XXX: this is (probably) a temporary entrypoint, as the range information should be available from the vertex_buffer state. Using this to quickly evaluate a specialized path in the draw module. ``draw_arrays_instanced`` draws multiple instances of the same primitive. This command is equivalent to calling ``draw_elements_instanced`` with ``indexBuffer`` set to NULL and ``indexSize`` set to 0. ``draw_elements_instanced`` draws multiple instances of the same primitive using an optional index buffer. For instanceID in the range between ``startInstance`` and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive specified by ``mode`` and sequential numbers in the range between ``start`` and ``start``+``count``-1, inclusive. If ``indexBuffer`` is not NULL, it specifies an index buffer with index byte size of ``indexSize``. The sequential numbers are used to lookup the index buffer and the resulting indices in turn are used to fetch vertex attributes. If ``indexBuffer`` is NULL, the sequential numbers are used directly as indices to fetch vertex attributes. If a given vertex element has ``instance_divisor`` set to 0, it is said it contains per-vertex data and effective vertex attribute address needs to be recalculated for every index. attribAddr = ``stride`` * index + ``src_offset`` If a given vertex element has ``instance_divisor`` set to non-zero, it is said it contains per-instance data and effective vertex attribute address needs to recalculated for every ``instance_divisor``-th instance. attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset`` In the above formulas, ``src_offset`` is taken from the given vertex element and ``stride`` is taken from a vertex buffer associated with the given vertex element. The calculated attribAddr is used as an offset into the vertex buffer to fetch the attribute data. The value of ``instanceID`` can be read in a vertex shader through a system value register declared with INSTANCEID semantic name. Queries ^^^^^^^ Queries gather some statistic from the 3D pipeline over one or more draws. Queries may be nested, though no state tracker currently exercises this. Queries can be created with ``create_query`` and deleted with ``destroy_query``. To enable a query, use ``begin_query``, and when finished, use ``end_query`` to stop the query. Finally, ``get_query_result`` is used to retrieve the results. Flushing ^^^^^^^^ ``flush`` Resource Busy Queries ^^^^^^^^^^^^^^^^^^^^^ ``is_texture_referenced`` ``is_buffer_referenced`` Blitting ^^^^^^^^ These methods emulate classic blitter controls. They are not guaranteed to be available; if they are set to NULL, then they are not present. These methods operate directly on ``pipe_surface`` objects, and stand apart from any 3D state in the context. Blitting functionality may be moved to a separate abstraction at some point in the future. ``surface_fill`` performs a fill operation on a section of a surface. ``surface_copy`` blits a region of a surface to a region of another surface, provided that both surfaces are the same format. The source and destination may be the same surface, and overlapping blits are permitted. The interfaces to these calls are likely to change to make it easier for a driver to batch multiple blits with the same source and destination.