diff options
| -rw-r--r-- | src/gallium/docs/source/context.rst | 79 |
1 files changed, 63 insertions, 16 deletions
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 6470e8fd492..21f5f9111a0 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -25,6 +25,21 @@ CSO objects handled by the context object: * :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 ^^^^^^^^^^^^^ @@ -35,47 +50,79 @@ objects. They all follow simple, one-method binding calls, e.g. * ``set_edgeflags`` * ``set_blend_color`` * ``set_clip_state`` -* ``set_constant_buffer`` -* ``set_framebuffer_state`` * ``set_polygon_stipple`` * ``set_scissor_state`` * ``set_viewport_state`` -* ``set_fragment_sampler_textures`` -* ``set_vertex_sampler_textures`` -* ``set_vertex_buffers`` * ``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`` + +``draw_elements`` + +``draw_range_elements`` + + 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. -VBO Drawing -^^^^^^^^^^^ +Flushing +^^^^^^^^ -``draw_arrays`` +``flush`` -``draw_elements`` -``draw_range_elements`` +Resource Busy Queries +^^^^^^^^^^^^^^^^^^^^^ -``flush`` +``is_texture_referenced`` -Surface Drawing -^^^^^^^^^^^^^^^ +``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. -``clear`` initializes entire buffers to an RGBA, depth, or stencil value, -depending on the formats of the buffers. Use ``set_framebuffer_state`` to -specify the buffers to clear. +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. + |