diff options
Diffstat (limited to 'src/gallium/docs/source/context.rst')
-rw-r--r-- | src/gallium/docs/source/context.rst | 93 |
1 files changed, 87 insertions, 6 deletions
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 9080addba4..7439d10097 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -24,6 +24,7 @@ CSO objects handled by the context object: * :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. +* :ref:`Vertex Elements`: ``*_vertex_elements_state`` Resource Binding State @@ -39,8 +40,7 @@ buffers, surfaces) are bound to the driver. are mostly restricted to the first one right now). * ``set_framebuffer_state`` -* ``set_fragment_sampler_textures`` -* ``set_vertex_sampler_textures`` + * ``set_vertex_buffers`` @@ -50,6 +50,7 @@ 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_blend_color``. + * ``set_stencil_ref`` sets the stencil front and back reference values which are used as comparison values in stencil test. * ``set_blend_color`` @@ -60,7 +61,41 @@ objects. They all follow simple, one-method binding calls, e.g. not have the scissor test enabled, then the scissor bounds never need to be set since they will not be used. * ``set_viewport_state`` -* ``set_vertex_elements`` + + +Sampler Views +^^^^^^^^^^^^^ + +These are the means to bind textures to shader stages. To create one, specify +its format, swizzle and LOD range in sampler view template. + +If texture format is different than template format, it is said the texture +is being cast to another format. Casting can be done only between compatible +formats, that is formats that have matching component order and sizes. + +Swizzle fields specify they way in which fetched texel components are placed +in the result register. For example, ``swizzle_r`` specifies what is going to be +placed in first component of result register. + +The ``first_level`` and ``last_level`` fields of sampler view template specify +the LOD range the texture is going to be constrained to. + +* ``set_fragment_sampler_views`` binds an array of sampler views to + fragment shader stage. Every binding point acquires a reference + to a respective sampler view and releases a reference to the previous + sampler view. + +* ``set_vertex_sampler_views`` binds an array of sampler views to vertex + shader stage. Every binding point acquires a reference to a respective + sampler view and releases a reference to the previous sampler view. + +* ``create_sampler_view`` creates a new sampler view. ``texture`` is associated + with the sampler view which results in sampler view holding a reference + to the texture. Format specified in template must be compatible + with texture format. + +* ``sampler_view_destroy`` destroys a sampler view and releases its reference + to associated texture. Clearing @@ -204,9 +239,7 @@ Flushing Resource Busy Queries ^^^^^^^^^^^^^^^^^^^^^ -``is_texture_referenced`` - -``is_buffer_referenced`` +``is_resource_referenced`` @@ -230,3 +263,51 @@ 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. + +Transfers +^^^^^^^^^ + +These methods are used to get data to/from a resource. + +``get_transfer`` creates a transfer object. + +``transfer_destroy`` destroys the transfer object. May cause +data to be written to the resource at this point. + +``transfer_map`` creates a memory mapping for the transfer object. +The returned map points to the start of the mapped range according to +the box region, not the beginning of the resource. + +.. _transfer_flush_region: +``transfer_flush_region`` If a transfer was created with TRANFER_FLUSH_EXPLICIT, +only the region specified is guaranteed to be written to. This is relative to +the mapped range, not the beginning of the resource. + +``transfer_unmap`` remove the memory mapping for the transfer object. +Any pointers into the map should be considered invalid and discarded. + +``transfer_inline_write`` performs a simplified transfer for simple writes. +Basically get_transfer, transfer_map, data write, transfer_unmap, and +transfer_destroy all in one. + +.. _pipe_transfer: + +PIPE_TRANSFER +^^^^^^^^^^^^^ + +These flags control the behavior of a transfer object. + +* ``READ``: resource contents are read at transfer create time. +* ``WRITE``: resource contents will be written back at transfer destroy time. +* ``MAP_DIRECTLY``: a transfer should directly map the resource. May return + NULL if not supported. +* ``DISCARD``: The memory within the mapped region is discarded. + Cannot be used with ``READ``. +* ``DONTBLOCK``: Fail if the resource cannot be mapped immediately. +* ``UNSYNCHRONIZED``: Do not synchronize pending operations on the resource + when mapping. The interaction of any writes to the map and any + operations pending on the resource are undefined. Cannot be used with + ``READ``. +* ``FLUSH_EXPLICIT``: Written ranges will be notified later with + :ref:`transfer_flush_region`. Cannot be used with + ``READ``. |