src/gallium/docs/source/context.rst

   1 Context
   2 =======
   3
   4 The context object represents the purest, most directly accessible, abilities
   5 of the device's 3D rendering pipeline.
   6
   7 Methods
   8 -------
   9
  10 CSO State
  11 ^^^^^^^^^
  12
  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``.
  16
  17 CSO objects handled by the context object:
  18
  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
  28
  29 Resource Binding State
  30 ^^^^^^^^^^^^^^^^^^^^^^
  31
  32 This state describes how resources in various flavours (textures,
  33 buffers, surfaces) are bound to the driver.
  34
  35
  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).
  40
  41 * ``set_framebuffer_state``
  42 * ``set_fragment_sampler_textures``
  43 * ``set_vertex_sampler_textures``
  44 * ``set_vertex_buffers``
  45
  46
  47 Non-CSO State
  48 ^^^^^^^^^^^^^
  49
  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.
  52 ``set_edgeflags``.
  53
  54 * ``set_blend_color``
  55 * ``set_clip_state``
  56 * ``set_polygon_stipple``
  57 * ``set_scissor_state``
  58 * ``set_viewport_state``
  59 * ``set_vertex_elements``
  60
  61
  62 Clearing
  63 ^^^^^^^^
  64
  65 ``clear`` initializes some or all of the surfaces currently bound to
  66 the framebuffer to particular RGBA, depth, or stencil values.
  67
  68 Clear is one of the most difficult concepts to nail down to a single
  69 interface and it seems likely that we will want to add additional
  70 clear paths, for instance clearing surfaces not bound to the
  71 framebuffer, or read-modify-write clears such as depth-only or
  72 stencil-only clears of packed depth-stencil buffers.
  73
  74
  75 Drawing
  76 ^^^^^^^
  77
  78 ``draw_arrays`` draws a specified primitive.
  79
  80 This command is equivalent to calling ``draw_arrays_instanced``
  81 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
  82
  83 ``draw_elements`` draws a specified primitive using an optional
  84 index buffer.
  85
  86 This command is equivalent to calling ``draw_elements_instanced``
  87 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
  88
  89 ``draw_range_elements``
  90
  91 XXX: this is (probably) a temporary entrypoint, as the range
  92 information should be available from the vertex_buffer state.
  93 Using this to quickly evaluate a specialized path in the draw
  94 module.
  95
  96 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
  97
  98 This command is equivalent to calling ``draw_elements_instanced``
  99 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
 100
 101 ``draw_elements_instanced`` draws multiple instances of the same primitive
 102 using an optional index buffer.
 103
 104 For instanceID in the range between ``startInstance``
 105 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
 106 specified by ``mode`` and sequential numbers in the range between ``start``
 107 and ``start``+``count``-1, inclusive.
 108
 109 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
 110 byte size of ``indexSize``. The sequential numbers are used to lookup
 111 the index buffer and the resulting indices in turn are used to fetch
 112 vertex attributes.
 113
 114 If ``indexBuffer`` is NULL, the sequential numbers are used directly
 115 as indices to fetch vertex attributes.
 116
 117 If a given vertex element has ``instance_divisor`` set to 0, it is said
 118 it contains per-vertex data and effective vertex attribute address needs
 119 to be recalculated for every index.
 120
 121   attribAddr = ``stride`` * index + ``src_offset``
 122
 123 If a given vertex element has ``instance_divisor`` set to non-zero,
 124 it is said it contains per-instance data and effective vertex attribute
 125 address needs to recalculated for every ``instance_divisor``-th instance.
 126
 127   attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
 128
 129 In the above formulas, ``src_offset`` is taken from the given vertex element
 130 and ``stride`` is taken from a vertex buffer associated with the given
 131 vertex element.
 132
 133 The calculated attribAddr is used as an offset into the vertex buffer to
 134 fetch the attribute data.
 135
 136 The value of ``instanceID`` can be read in a vertex shader through a system
 137 value register declared with INSTANCEID semantic name.
 138
 139
 140 Queries
 141 ^^^^^^^
 142
 143 Queries gather some statistic from the 3D pipeline over one or more
 144 draws.  Queries may be nested, though no state tracker currently
 145 exercises this.
 146
 147 Queries can be created with ``create_query`` and deleted with
 148 ``destroy_query``. To enable a query, use ``begin_query``, and when finished,
 149 use ``end_query`` to stop the query. Finally, ``get_query_result`` is used
 150 to retrieve the results.
 151
 152 Flushing
 153 ^^^^^^^^
 154
 155 ``flush``
 156
 157
 158 Resource Busy Queries
 159 ^^^^^^^^^^^^^^^^^^^^^
 160
 161 ``is_texture_referenced``
 162
 163 ``is_buffer_referenced``
 164
 165
 166
 167 Blitting
 168 ^^^^^^^^
 169
 170 These methods emulate classic blitter controls. They are not guaranteed to be
 171 available; if they are set to NULL, then they are not present.
 172
 173 These methods operate directly on ``pipe_surface`` objects, and stand
 174 apart from any 3D state in the context.  Blitting functionality may be
 175 moved to a separate abstraction at some point in the future.
 176
 177 ``surface_fill`` performs a fill operation on a section of a surface.
 178
 179 ``surface_copy`` blits a region of a surface to a region of another surface,
 180 provided that both surfaces are the same format. The source and destination
 181 may be the same surface, and overlapping blits are permitted.
 182
 183 The interfaces to these calls are likely to change to make it easier
 184 for a driver to batch multiple blits with the same source and
 185 destination.
 186