gallium/docs: improve text about resources a bit.

This clarifies some things and gets rid of some old stuff.
The most significant one is probably that buffers cannot have formats
(nearly all drivers completely ignored format and used width0 as byte size
already in any case). There seems to be no use case for "structured" buffers.
(Note while d3d11 has new Structured Buffers, these still aren't associated
with a format, rather a byte stride, which we can't do yet either way.)

Reviewed-by: Jose Fonseca <jfonseca@vmware.com>

diff --git a/src/gallium/docs/source/resources.rst b/src/gallium/docs/source/resources.rst
index c8a5766821b8a0b110e63c8fbb3f7efd4a646a9f..553e335dcf9fe8963e49c44009966a66194b40c4 100644 (file)
--- a/src/gallium/docs/source/resources.rst
+++ b/src/gallium/docs/source/resources.rst
@@ -34,44 +34,52 @@ will probably be advertised with an appropriate cap.
 TODO: document all targets. Note that both 3D and cube have restrictions
 that depend on the hardware generation.
 
-TODO: can buffers have a non-R8 format?
 
 PIPE_BUFFER
 ^^^^^^^^^^^
 
-Buffer resource: can be used as a vertex, index, constant buffer (appropriate bind flags must be requested).
+Buffer resource: can be used as a vertex, index, constant buffer
+(appropriate bind flags must be requested).
+
+Buffers do not really have a format, it's just bytes, but they are required
+to have their type set to a R8 format (without a specific "just byte" format,
+R8_UINT would probably make the most sense, but for historic reasons R8_UNORM
+is ok too). (This is just to make some shared buffer/texture code easier so
+format size can be queried.)
+width0 serves as size, most other resource properties don't apply but must be
+set appropriately (depth0/height0/array_size must be 1, last_level 0).
 
 They can be bound to stream output if supported.
 TODO: what about the restrictions lifted by the several later GL transform feedback extensions? How does one advertise that in Gallium?
 
-They can be also be bound to a shader stage as usual.
-TODO: are all drivers supposed to support this? how does this work exactly? are there size limits?
-
-They can be also be bound to the framebuffer as usual.
-TODO: are all drivers supposed to support this? how does this work exactly? are there size limits?
+They can be also be bound to a shader stage (for sampling) as usual by
+creating an appropriate sampler view, if the driver supports PIPE_CAP_TEXTURE_BUFFER_OBJECTS.
+This supports larger width than a 1d texture would
+(TODO limit currently unspecified, minimum must be at least 65536).
+Only the "direct fetch" sample opcodes are supported (TGSI_OPCODE_TXF,
+TGSI_OPCODE_SAMPLE_I) so the sampler state (coord wrapping etc.)
+is mostly ignored (with SAMPLE_I there's no sampler state at all).
+
+They can be also be bound to the framebuffer (only as color render target, not
+depth buffer, also there cannot be a depth buffer bound at the same time) as usual
+by creating an appropriate view (this is not usable in OpenGL).
+TODO there's no CAP bit currently for this, there's also unspecified size etc. limits
 TODO: is there any chance of supporting GL pixel buffer object acceleration with this?
 
-- depth0 must be 1
-- last_level must be 0
-- TODO: what about normalization?
-- TODO: wrap modes/other sampling state?
-- TODO: are arbitrary formats supported? in which cases?
 
 OpenGL: vertex buffers in GL 1.5 or GL_ARB_vertex_buffer_object
 
 - Binding to stream out requires GL 3.0 or GL_NV_transform_feedback
 - Binding as constant buffers requires GL 3.1 or GL_ARB_uniform_buffer_object
 - Binding to a sampling stage requires GL 3.1 or GL_ARB_texture_buffer_object
-- TODO: can they be bound to an FBO?
 
 D3D11: buffer resources
 - Binding to a render target requires D3D_FEATURE_LEVEL_10_0
 
-PIPE_TEXTURE_1D
-^^^^^^^^^^^^^^^
+PIPE_TEXTURE_1D / PIPE_TEXTURE_1D_ARRAY
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 1D surface accessed with normalized coordinates.
-
-UNIMPLEMENTED: 1D texture arrays not supported
+1D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS.
 
 - If PIPE_CAP_NPOT_TEXTURES is not supported,
       width must be a power of two
@@ -101,11 +109,10 @@ OpenCL: can create OpenCL images based on this, that can then be sampled arbitra
 
 D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported)
 
-PIPE_TEXTURE_2D
-^^^^^^^^^^^^^^^
+PIPE_TEXTURE_2D / PIPE_TEXTURE_2D_ARRAY
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 2D surface accessed with normalized coordinates.
-
-UNIMPLEMENTED: 2D texture arrays not supported
+2D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS.
 
 - If PIPE_CAP_NPOT_TEXTURES is not supported,
       width and height must be powers of two
@@ -142,18 +149,16 @@ D3D11: 3D textures
 
 - PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0
 
-PIPE_TEXTURE_CUBE
-^^^^^^^^^^^^^^^^^
+PIPE_TEXTURE_CUBE / PIPE_TEXTURE_CUBE_ARRAY
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Cube maps consist of 6 2D faces.
 The 6 surfaces form an imaginary cube, and sampling happens by mapping an
 input 3-vector to the point of the cube surface in that direction.
+Cube map arrays are supported depending on PIPE_CAP_CUBE_MAP_ARRAY.
 
-Sampling may be optionally seamless, resulting in filtering taking samples
-from multiple surfaces near to the edge.
-UNIMPLEMENTED: seamless cube map sampling not supported
-
-UNIMPLEMENTED: cube map arrays not supported
+Sampling may be optionally seamless if a driver supports it (PIPE_CAP_SEAMLESS_CUBE_MAP),
+resulting in filtering taking samples from multiple surfaces near to the edge.
 
 - Width and height must be equal
 - If PIPE_CAP_NPOT_TEXTURES is not supported,
@@ -170,7 +175,6 @@ D3D11: 2D array textures with the D3D11_RESOURCE_MISC_TEXTURECUBE flag
 
 - PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0
 - Cube map arrays require D3D_FEATURE_LEVEL_10_1
-- TODO: are (non)seamless cube maps supported in D3D11? how?
 
 Surfaces
 --------