Context
=======
-The context object represents the purest, most directly accessible, abilities
-of the device's 3D rendering pipeline.
+A Gallium rendering context encapsulates the state which effects 3D
+rendering such as blend state, depth/stencil state, texture samplers,
+etc.
+
+Note that resource/texture allocation is not per-context but per-screen.
+
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``.
+All Constant State Object (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:`Sampler`: Texture sampler states are bound separately for fragment,
+ vertex and geometry samplers. Note that sampler states are set en masse.
+ If M is the max number of sampler units supported by the driver and N
+ samplers are bound with ``bind_fragment_sampler_states`` then sampler
+ units N..M-1 are considered disabled/NULL.
* :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.
+* :ref:`Shader`: These are create, bind and destroy methods for vertex,
+ fragment and geometry shaders.
* :ref:`Vertex Elements`: ``*_vertex_elements_state``
* ``set_index_buffer``
+* ``set_stream_output_buffers``
+
+
Non-CSO State
^^^^^^^^^^^^^
* ``set_scissor_state`` sets the bounds for the scissor test, which culls
pixels before blending to render targets. If the :ref:`Rasterizer` does
not have the scissor test enabled, then the scissor bounds never need to
- be set since they will not be used.
+ be set since they will not be used. Note that scissor xmin and ymin are
+ inclusive, but xmax and ymax are exclusive. The inclusive ranges in x
+ and y would be [xmin..xmax-1] and [ymin..ymax-1].
* ``set_viewport_state``
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.
+the LOD range the texture is going to be constrained to. Note that these
+values are in addition to the respective min_lod, max_lod values in the
+pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip
+level used for sampling from the resource is effectively the fifth).
+
+The ``first_layer`` and ``last_layer`` fields specify the layer range the
+texture is going to be constrained to. Similar to the LOD range, this is added
+to the array index which is used for sampling.
* ``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.
+ sampler view. If M is the maximum number of sampler units and N units
+ is passed to set_fragment_sampler_views, the driver should unbind the
+ sampler views for units N..M-1.
* ``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_destroy`` destroys a sampler view and releases its reference
to associated texture.
+Surfaces
+^^^^^^^^
+
+These are the means to use resources as color render targets or depthstencil
+attachments. To create one, specify the mip level, the range of layers, and
+the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
+Note that layer values are in addition to what is indicated by the geometry
+shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
+shader indicates index 2, the 5th layer of the resource will be used). These
+first_layer and last_layer parameters will only be used for 1d array, 2d array,
+cube, and 3d textures otherwise they are 0.
+
+* ``create_surface`` creates a new surface.
+
+* ``surface_destroy`` destroys a surface and releases its reference to the
+ associated resource.
Clearing
^^^^^^^^
GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
only depth or stencil in a combined depth/stencil surface, if the driver
supports PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE.
-If a surface includes several layers/slices (XXX: not yet...) then all layers
-will be cleared.
+If a surface includes several layers then all layers will be cleared.
``clear_render_target`` clears a single color rendertarget with the specified
color value. While it is only possible to clear one surface at a time (which can
Every instance with instanceID in the range between ``start_instance`` and
``start_instance``+``instance_count``-1, inclusive, will be drawn.
-All vertex indices must fall inside the range given by ``min_index`` and
-``max_index``. In case non-indexed draw, ``min_index`` should be set to
+If there is an index buffer bound, and ``indexed`` field is true, all vertex
+indices will be looked up in the index buffer.
+
+In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower
+and upper bound of the indices contained in the index buffer inside the range
+between ``start`` to ``start``+``count``-1. This allows the driver to
+determine which subset of vertices will be referenced during te draw call
+without having to scan the index buffer. Providing a over-estimation of the
+the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and
+0xffffffff respectively, must give exactly the same rendering, albeit with less
+performance due to unreferenced vertex buffers being unnecessarily DMA'ed or
+processed. Providing a underestimation of the true bounds will result in
+undefined behavior, but should not result in program or system failure.
+
+In case of non-indexed draw, ``min_index`` should be set to
``start`` and ``max_index`` should be set to ``start``+``count``-1.
-``index_bias`` is a value added to every vertex index before fetching vertex
-attributes. It does not affect ``min_index`` and ``max_index``.
+``index_bias`` is a value added to every vertex index after lookup and before
+fetching vertex attributes.
-If there is an index buffer bound, and ``indexed`` field is true, all vertex
-indices will be looked up in the index buffer. ``min_index``, ``max_index``,
-and ``index_bias`` apply after index lookup.
+When drawing indexed primitives, the primitive restart index can be
+used to draw disjoint primitive strips. For example, several separate
+line strips can be drawn by designating a special index value as the
+restart index. The ``primitive_restart`` flag enables/disables this
+feature. The ``restart_index`` field specifies the restart index value.
+
+When primitive restart is in use, array indexes are compared to the
+restart index before adding the index_bias offset.
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
^^^^^^^
Queries gather some statistic from the 3D pipeline over one or more
-draws. Queries may be nested, though no state tracker currently
-exercises this.
+draws. Queries may be nested, though only d3d1x currently exercises this.
Queries can be created with ``create_query`` and deleted with
``destroy_query``. To start a query, use ``begin_query``, and when finished,
will not block and the return value will be TRUE if the query has
completed or FALSE otherwise.
-The most common type of query is the occlusion query,
-``PIPE_QUERY_OCCLUSION_COUNTER``, which counts the number of fragments which
+The interface currently includes the following types of queries:
+
+``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which
are written to the framebuffer without being culled by
:ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
-
-Another type of query, ``PIPE_QUERY_TIME_ELAPSED``, returns the amount of
-time, in nanoseconds, the context takes to perform operations.
+The result is an unsigned 64-bit integer.
+This query can be used with ``render_condition``.
+
+In cases where a boolean result of an occlusion query is enough,
+``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
+``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
+value of FALSE for cases where COUNTER would result in 0 and TRUE
+for all other cases.
+This query can be used with ``render_condition``.
+
+``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
+the context takes to perform operations.
+The result is an unsigned 64-bit integer.
+
+``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp,
+scaled to nanoseconds, recorded after all commands issued prior to
+``end_query`` have been processed.
+This query does not require a call to ``begin_query``.
+The result is an unsigned 64-bit integer.
+
+``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check whether the
+internal timer resolution is good enough to distinguish between the
+events at ``begin_query`` and ``end_query``.
+The result is a 64-bit integer specifying the timer resolution in Hz,
+followed by a boolean value indicating whether the timer has incremented.
+
+``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating
+the number of primitives processed by the pipeline.
+
+``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating
+the number of primitives written to stream output buffers.
+
+``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to
+the results of
+``PIPE_QUERY_PRIMITIVES_EMITTED`` and
+``PIPE_QUERY_PRIMITIVES_GENERATED``, in this order.
+
+``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
+whether the stream output targets have overflowed as a result of the
+commands issued between ``begin_query`` and ``end_query``.
+This query can be used with ``render_condition``.
+
+``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
+all commands issued before ``end_query`` have completed. However, this
+does not imply serialization.
+This query does not require a call to ``begin_query``.
+
+``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following
+64-bit integers:
+Number of vertices read from vertex buffers.
+Number of primitives read from vertex buffers.
+Number of vertex shader threads launched.
+Number of geometry shader threads launched.
+Number of primitives generated by geometry shaders.
+Number of primitives forwarded to the rasterizer.
+Number of primitives rasterized.
+Number of fragment shader threads launched.
+Number of tessellation control shader threads launched.
+Number of tessellation evaluation shader threads launched.
+If a shader type is not supported by the device/driver,
+the corresponding values should be set to 0.
Gallium does not guarantee the availability of any query types; one must
always check the capabilities of the :ref:`Screen` first.
apart from any 3D state in the context. Blitting functionality may be
moved to a separate abstraction at some point in the future.
-``resource_copy_region`` blits a region of a subresource of a resource to a
-region of another subresource of a resource, provided that both resources have the
-same format. The source and destination may be the same resource, but overlapping
-blits are not permitted.
+``resource_copy_region`` blits a region of a resource to a region of another
+resource, provided that both resources have the same format, or compatible
+formats, i.e., formats for which copying the bytes from the source resource
+unmodified to the destination resource will achieve the same effect of a
+textured quad blitter.. The source and destination may be the same resource,
+but overlapping blits are not permitted.
``resource_resolve`` resolves a multisampled resource into a non-multisampled
-one. Formats and dimensions must match. This function must be present if a driver
+one. Their formats must match. This function must be present if a driver
supports multisampling.
+The region that is to be resolved is described by ``pipe_resolve_info``, which
+provides a source and a destination rectangle.
+The source rectangle may be vertically flipped, but otherwise the dimensions
+of the rectangles must match, unless PIPE_CAP_SCALED_RESOLVE is supported,
+in which case scaling and horizontal flipping are allowed as well.
+The result of resolving depth/stencil values may be any function of the values at
+the sample points, but returning the value of the centermost sample is preferred.
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
Basically get_transfer, transfer_map, data write, transfer_unmap, and
transfer_destroy all in one.
+
+The box parameter to some of these functions defines a 1D, 2D or 3D
+region of pixels. This is self-explanatory for 1D, 2D and 3D texture
+targets.
+
+For PIPE_TEXTURE_1D_ARRAY, the box::y and box::height fields refer to the
+array dimension of the texture.
+
+For PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth fields refer to the
+array dimension of the texture.
+
+For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
+faces of the cube map (z + depth <= 6).
+
+
+
.. _transfer_flush_region:
transfer_flush_region
``transfer_flush_region``. Flush ranges are relative to the mapped range, not
the beginning of the resource.
+
+
+.. _redefine_user_buffer:
+
+redefine_user_buffer
+%%%%%%%%%%%%%%%%%%%%
+
+This function notifies a driver that the user buffer content has been changed.
+The updated region starts at ``offset`` and is ``size`` bytes large.
+The ``offset`` is relative to the pointer specified in ``user_buffer_create``.
+While uploading the user buffer, the driver is allowed not to upload
+the memory outside of this region.
+The width0 is redefined to ``MAX2(width0, offset+size)``.
+
+
+
+.. _texture_barrier
+
+texture_barrier
+%%%%%%%%%%%%%%%
+
+This function flushes all pending writes to the currently-set surfaces and
+invalidates all read caches of the currently-set samplers.
+
+
+
.. _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``.
+``PIPE_TRANSFER_READ``
+ Resource contents read back (or accessed directly) at transfer create time.
+
+``PIPE_TRANSFER_WRITE``
+ Resource contents will be written back at transfer_destroy time (or modified
+ as a result of being accessed directly).
+
+``PIPE_TRANSFER_MAP_DIRECTLY``
+ a transfer should directly map the resource. May return NULL if not supported.
+
+``PIPE_TRANSFER_DISCARD_RANGE``
+ The memory within the mapped region is discarded. Cannot be used with
+ ``PIPE_TRANSFER_READ``.
+
+``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE``
+ Discards all memory backing the resource. It should not be used with
+ ``PIPE_TRANSFER_READ``.
+
+``PIPE_TRANSFER_DONTBLOCK``
+ Fail if the resource cannot be mapped immediately.
+
+``PIPE_TRANSFER_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 ``PIPE_TRANSFER_READ``.
+
+``PIPE_TRANSFER_FLUSH_EXPLICIT``
+ Written ranges will be notified later with :ref:`transfer_flush_region`.
+ Cannot be used with ``PIPE_TRANSFER_READ``.
projects / mesa.git / blobdiff