[Mesa-dev] [PATCH 1/2] gallium/docs: improve text about resources a bit.

[Jose Fonseca]

----- Original Message -----
> From: Roland Scheidegger <sroland at vmware.com>
> 
> 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.)
> ---
>  src/gallium/docs/source/resources.rst |   62
>  ++++++++++++++++++---------------
>  1 file changed, 33 insertions(+), 29 deletions(-)
> 
> diff --git a/src/gallium/docs/source/resources.rst
> b/src/gallium/docs/source/resources.rst
> index c8a5766..553e335 100644
> --- 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
>  --------
> --
> 1.7.9.5
> 

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