+.. _resource:
+
Resources and derived objects
=============================
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
- height0 must be 1
- depth0 must be 1
+- array_size must be 1 for PIPE_TEXTURE_1D
- Mipmaps can be used
- Must use normalized coordinates
2D surface with OpenGL GL_TEXTURE_RECTANGLE semantics.
- depth0 must be 1
+- array_size must be 1
- last_level must be 0
- Must use unnormalized coordinates
- Must use a clamp wrap mode
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
- depth0 must be 1
+- array_size must be 1 for PIPE_TEXTURE_2D
- Mipmaps can be used
- Must use normalized coordinates
- No special restrictions on wrap modes
- If PIPE_CAP_NPOT_TEXTURES is not supported,
width, height and depth must be powers of two
+- array_size must be 1
- Must use normalized coordinates
OpenGL: GL_TEXTURE_3D in GL 1.2 or GL_EXT_texture3D
- 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
+- depth0 must be 1
+- array_size must be a multiple of 6
- If PIPE_CAP_NPOT_TEXTURES is not supported,
width and height must be powers of two
- Must use normalized coordinates
- 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
--------
projects / mesa.git / blobdiff