aboutsummaryrefslogtreecommitdiffstats
path: root/src/gallium/docs
diff options
context:
space:
mode:
Diffstat (limited to 'src/gallium/docs')
-rw-r--r--src/gallium/docs/source/context.rst41
-rw-r--r--src/gallium/docs/source/screen.rst110
-rw-r--r--src/gallium/docs/source/tgsi.rst111
3 files changed, 259 insertions, 3 deletions
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index d394f5b4f1b..78b01cc9cbe 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -54,7 +54,10 @@ objects. They all follow simple, one-method binding calls, e.g.
* ``set_blend_color``
* ``set_clip_state``
* ``set_polygon_stipple``
-* ``set_scissor_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.
* ``set_viewport_state``
* ``set_vertex_elements``
@@ -149,6 +152,42 @@ Queries can be created with ``create_query`` and deleted with
use ``end_query`` to stop the query. Finally, ``get_query_result`` is used
to retrieve the results.
+A common type of query is the occlusion query which counts the number of
+fragments/pixels which are written to the framebuffer (and not culled by
+Z/stencil/alpha testing or shader KILL instructions).
+
+
+Conditional Rendering
+^^^^^^^^^^^^^^^^^^^^^
+
+A drawing command can be skipped depending on the outcome of a query
+(typically an occlusion query). The ``render_condition`` function specifies
+the query which should be checked prior to rendering anything.
+
+If ``render_condition`` is called with ``query`` = NULL, conditional
+rendering is disabled and drawing takes place normally.
+
+If ``render_condition`` is called with a non-null ``query`` subsequent
+drawing commands will be predicated on the outcome of the query. If
+the query result is zero subsequent drawing commands will be skipped.
+
+If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
+query to complete before deciding whether to render.
+
+If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
+completed, the drawing command will be executed normally. If the query
+has completed, drawing will be predicated on the outcome of the query.
+
+If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
+PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
+for the non-REGION modes but in the case that an occulusion query returns
+a non-zero result, regions which were occluded may be ommitted by subsequent
+drawing commands. This can result in better performance with some GPUs.
+Normally, if the occlusion query returned a non-zero result subsequent
+drawing happens normally so fragments may be generated, shaded and
+processed even where they're known to be obscured.
+
+
Flushing
^^^^^^^^
diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
index 72bb75a55dc..905ff24db99 100644
--- a/src/gallium/docs/source/screen.rst
+++ b/src/gallium/docs/source/screen.rst
@@ -6,6 +6,41 @@ A screen is an object representing the context-independent part of a device.
Useful Flags
------------
+.. _pipe_buffer_usage:
+
+PIPE_BUFFER_USAGE
+^^^^^^^^^^^^^^^^^
+
+These flags control buffer creation. Buffers may only have one role, so
+care should be taken to not allocate a buffer with the wrong usage.
+
+* ``PIXEL``: This is the flag to use for all textures.
+* ``VERTEX``: A vertex buffer.
+* ``INDEX``: An element buffer.
+* ``CONSTANT``: A buffer of shader constants.
+
+Buffers are inevitably abstracting the pipe's underlying memory management,
+so many of their usage flags can be used to direct the way the buffer is
+handled.
+
+* ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of
+ the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is
+ available to signify a read/write buffer.
+* ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to
+ read from or write to the buffer. The latter will only happen if the buffer
+ is made into a render target.
+* ``DISCARD``: When set on a map, the contents of the map will be discarded
+ beforehand. Cannot be used with ``CPU_READ``.
+* ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be
+ mapped immediately.
+* ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the
+ buffer will be ignored. The interaction of any writes to the map and any
+ operations pending with the buffer are undefined. Cannot be used with
+ ``CPU_READ``.
+* ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require
+ explicit flushes using :ref:`buffer_flush_mapped_range`. Requires
+ ``CPU_WRITE``.
+
.. _pipe_texture_usage:
PIPE_TEXTURE_USAGE
@@ -43,7 +78,29 @@ Returns the screen vendor.
get_param
^^^^^^^^^
-Get an integer/boolean screen parameter.
+Get an integer/boolean screen parameter. Valid parameter names include.
+
+* ``PIPE_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that
+ can be bound to any shader stage using ``set_constant_buffer``.
+
+ If 0 is returned, the driver is not aware of multiple constant buffers,
+ supports binding of only one constant buffer, and does not support
+ two-dimensional CONST register file access in TGSI shaders.
+
+ If a value greater than 0 is returned, the driver can have multiple
+ constant buffers bound to shader stages. The CONST register file can
+ be accessed with two-dimensional indices, like in the example below.
+
+ DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
+ DCL CONST[3][0] # declare first vector of constbuf 3
+ MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
+
+ For backwards compatibility, one-dimensional access to CONST register
+ file is still supported. In that case, the constbuf index is assumed
+ to be 0.
+
+* ``PIPE_CAP_MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant
+ buffer.
get_paramf
^^^^^^^^^^
@@ -63,7 +120,56 @@ Returns TRUE if all usages can be satisfied.
``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage.
+.. _texture_create:
+
texture_create
^^^^^^^^^^^^^^
-Given a template of texture setup, create a BO-backed texture.
+Given a template of texture setup, create a buffer and texture.
+
+texture_blanket
+^^^^^^^^^^^^^^^
+
+Like :ref:`texture_create`, but use a supplied buffer instead of creating a
+new one.
+
+texture_destroy
+^^^^^^^^^^^^^^^
+
+Destroy a texture. The buffer backing the texture is destroyed if it has no
+more references.
+
+buffer_map
+^^^^^^^^^^
+
+Map a buffer into memory.
+
+**usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
+
+Returns a pointer to the map, or NULL if the mapping failed.
+
+buffer_map_range
+^^^^^^^^^^^^^^^^
+
+Map a range of a buffer into memory.
+
+The returned map is always relative to the beginning of the buffer, not the
+beginning of the mapped range.
+
+.. _buffer_flush_mapped_range:
+
+buffer_flush_mapped_range
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Flush a range of mapped memory into a buffer.
+
+The buffer must have been mapped with ``PIPE_BUFFER_USAGE_FLUSH_EXPLICIT``.
+
+**usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
+
+buffer_unmap
+^^^^^^^^^^^^
+
+Unmap a buffer from memory.
+
+Any pointers into the map should be considered invalid and discarded.
diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst
index 65a669d8cfa..2c34a6bae5e 100644
--- a/src/gallium/docs/source/tgsi.rst
+++ b/src/gallium/docs/source/tgsi.rst
@@ -1111,6 +1111,117 @@ BREAKC - Break Conditional
TBD
+Double Opcodes
+^^^^^^^^^^^^^^^
+
+DADD - Add Double
+
+.. math::
+
+ dst.xy = src0.xy + src1.xy
+
+ dst.zw = src0.zw + src1.zw
+
+
+DDIV - Divide Double
+
+.. math::
+
+ dst.xy = src0.xy / src1.xy
+
+ dst.zw = src0.zw / src1.zw
+
+DSEQ - Set Double on Equal
+
+.. math::
+
+ dst.xy = src0.xy == src1.xy ? 1.0F : 0.0F
+
+ dst.zw = src0.zw == src1.zw ? 1.0F : 0.0F
+
+DSLT - Set Double on Less than
+
+.. math::
+
+ dst.xy = src0.xy < src1.xy ? 1.0F : 0.0F
+
+ dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F
+
+DFRAC - Double Fraction
+
+.. math::
+
+ dst.xy = src.xy - \lfloor src.xy\rfloor
+
+ dst.zw = src.zw - \lfloor src.zw\rfloor
+
+
+DFRACEXP - Convert Double Number to Fractional and Integral Components
+
+.. math::
+
+ dst0.xy = frexp(src.xy, dst1.xy)
+
+ dst0.zw = frexp(src.zw, dst1.zw)
+
+DLDEXP - Multiple Double Number by Integral Power of 2
+
+.. math::
+
+ dst.xy = ldexp(src0.xy, src1.xy)
+
+ dst.zw = ldexp(src0.zw, src1.zw)
+
+DMIN - Minimum Double
+
+.. math::
+
+ dst.xy = min(src0.xy, src1.xy)
+
+ dst.zw = min(src0.zw, src1.zw)
+
+DMAX - Maximum Double
+
+.. math::
+
+ dst.xy = max(src0.xy, src1.xy)
+
+ dst.zw = max(src0.zw, src1.zw)
+
+DMUL - Multiply Double
+
+.. math::
+
+ dst.xy = src0.xy \times src1.xy
+
+ dst.zw = src0.zw \times src1.zw
+
+
+DMAD - Multiply And Add Doubles
+
+.. math::
+
+ dst.xy = src0.xy \times src1.xy + src2.xy
+
+ dst.zw = src0.zw \times src1.zw + src2.zw
+
+
+DRCP - Reciprocal Double
+
+.. math::
+
+ dst.xy = \frac{1}{src.xy}
+
+ dst.zw = \frac{1}{src.zw}
+
+DSQRT - Square root double
+
+.. math::
+
+ dst.xy = \sqrt{src.xy}
+
+ dst.zw = \sqrt{src.zw}
+
Explanation of symbols used
------------------------------