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``
  37 * ``set_framebuffer_state``
  38 * ``set_fragment_sampler_textures``
  39 * ``set_vertex_sampler_textures``
  40 * ``set_vertex_buffers``
  41
  42
  43 Non-CSO State
  44 ^^^^^^^^^^^^^
  45
  46 These pieces of state are too small, variable, and/or trivial to have CSO
  47 objects. They all follow simple, one-method binding calls, e.g.
  48 ``set_edgeflags``.
  49
  50 * ``set_edgeflags``
  51 * ``set_blend_color``
  52 * ``set_clip_state``
  53 * ``set_polygon_stipple``
  54 * ``set_scissor_state``
  55 * ``set_viewport_state``
  56 * ``set_vertex_elements``
  57
  58
  59 Clearing
  60 ^^^^^^^^
  61
  62 ``clear`` initializes some or all of the surfaces currently bound to
  63 the framebuffer to particular RGBA, depth, or stencil values.
  64
  65 Clear is one of the most difficult concepts to nail down to a single
  66 interface and it seems likely that we will want to add additional
  67 clear paths, for instance clearing surfaces not bound to the
  68 framebuffer, or read-modify-write clears such as depth-only or
  69 stencil-only clears of packed depth-stencil buffers.
  70
  71
  72 Drawing
  73 ^^^^^^^
  74
  75 ``draw_arrays``
  76
  77 ``draw_elements``
  78
  79 ``draw_range_elements``
  80
  81
  82 Queries
  83 ^^^^^^^
  84
  85 Queries gather some statistic from the 3D pipeline over one or more
  86 draws.  Queries may be nested, though no state tracker currently
  87 exercises this.
  88
  89 Queries can be created with ``create_query`` and deleted with
  90 ``destroy_query``. To enable a query, use ``begin_query``, and when finished,
  91 use ``end_query`` to stop the query. Finally, ``get_query_result`` is used
  92 to retrieve the results.
  93
  94 Flushing
  95 ^^^^^^^^
  96
  97 ``flush``
  98
  99
 100 Resource Busy Queries
 101 ^^^^^^^^^^^^^^^^^^^^^
 102
 103 ``is_texture_referenced``
 104
 105 ``is_buffer_referenced``
 106
 107
 108
 109 Blitting
 110 ^^^^^^^^
 111
 112 These methods emulate classic blitter controls. They are not guaranteed to be
 113 available; if they are set to NULL, then they are not present.
 114
 115 These methods operate directly on ``pipe_surface`` objects, and stand
 116 apart from any 3D state in the context.  Blitting functionality may be
 117 moved to a separate abstraction at some point in the future.
 118
 119 ``surface_fill`` performs a fill operation on a section of a surface.
 120
 121 ``surface_copy`` blits a region of a surface to a region of another surface,
 122 provided that both surfaces are the same format. The source and destination
 123 may be the same surface, and overlapping blits are permitted.
 124
 125 The interfaces to these calls are likely to change to make it easier
 126 for a driver to batch multiple blits with the same source and
 127 destination.
 128