1.. _resource:
2
3Resources and derived objects
4=============================
5
6Resources represent objects that hold data: textures and buffers.
7
8They are mostly modelled after the resources in Direct3D 10/11, but with a
9different transfer/update mechanism, and more features for OpenGL support.
10
11Resources can be used in several ways, and it is required to specify all planned uses through an appropriate set of bind flags.
12
13TODO: write much more on resources
14
15Transfers
16---------
17
18Transfers are the mechanism used to access resources with the CPU.
19
20OpenGL: OpenGL supports mapping buffers and has inline transfer functions for both buffers and textures
21
22D3D11: D3D11 lacks transfers, but has special resource types that are mappable to the CPU address space
23
24TODO: write much more on transfers
25
26Resource targets
27----------------
28
29Resource targets determine the type of a resource.
30
31Note that drivers may not actually have the restrictions listed regarding
32coordinate normalization and wrap modes, and in fact efficient OpenCL
33support will probably require drivers that don't have any of them, which
34will probably be advertised with an appropriate cap.
35
36TODO: document all targets. Note that both 3D and cube have restrictions
37that depend on the hardware generation.
38
39
40PIPE_BUFFER
41^^^^^^^^^^^
42
43Buffer resource: can be used as a vertex, index, constant buffer
44(appropriate bind flags must be requested).
45
46Buffers do not really have a format, it's just bytes, but they are required
47to have their type set to a R8 format (without a specific "just byte" format,
48R8_UINT would probably make the most sense, but for historic reasons R8_UNORM
49is ok too). (This is just to make some shared buffer/texture code easier so
50format size can be queried.)
51width0 serves as size, most other resource properties don't apply but must be
52set appropriately (depth0/height0/array_size must be 1, last_level 0).
53
54They can be bound to stream output if supported.
55TODO: what about the restrictions lifted by the several later GL transform feedback extensions? How does one advertise that in Gallium?
56
57They can be also be bound to a shader stage (for sampling) as usual by
58creating an appropriate sampler view, if the driver supports PIPE_CAP_TEXTURE_BUFFER_OBJECTS.
59This supports larger width than a 1d texture would
60(TODO limit currently unspecified, minimum must be at least 65536).
61Only the "direct fetch" sample opcodes are supported (TGSI_OPCODE_TXF,
62TGSI_OPCODE_SAMPLE_I) so the sampler state (coord wrapping etc.)
63is mostly ignored (with SAMPLE_I there's no sampler state at all).
64
65They can be also be bound to the framebuffer (only as color render target, not
66depth buffer, also there cannot be a depth buffer bound at the same time) as usual
67by creating an appropriate view (this is not usable in OpenGL).
68TODO there's no CAP bit currently for this, there's also unspecified size etc. limits
69TODO: is there any chance of supporting GL pixel buffer object acceleration with this?
70
71
72OpenGL: vertex buffers in GL 1.5 or GL_ARB_vertex_buffer_object
73
74- Binding to stream out requires GL 3.0 or GL_NV_transform_feedback
75- Binding as constant buffers requires GL 3.1 or GL_ARB_uniform_buffer_object
76- Binding to a sampling stage requires GL 3.1 or GL_ARB_texture_buffer_object
77
78D3D11: buffer resources
79- Binding to a render target requires D3D_FEATURE_LEVEL_10_0
80
81PIPE_TEXTURE_1D / PIPE_TEXTURE_1D_ARRAY
82^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
831D surface accessed with normalized coordinates.
841D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS.
85
86- If PIPE_CAP_NPOT_TEXTURES is not supported,
87      width must be a power of two
88- height0 must be 1
89- depth0 must be 1
90- array_size must be 1 for PIPE_TEXTURE_1D
91- Mipmaps can be used
92- Must use normalized coordinates
93
94OpenGL: GL_TEXTURE_1D in GL 1.0
95
96- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two
97
98D3D11: 1D textures in D3D_FEATURE_LEVEL_10_0
99
100PIPE_TEXTURE_RECT
101^^^^^^^^^^^^^^^^^
1022D surface with OpenGL GL_TEXTURE_RECTANGLE semantics.
103
104- depth0 must be 1
105- array_size must be 1
106- last_level must be 0
107- Must use unnormalized coordinates
108- Must use a clamp wrap mode
109
110OpenGL: GL_TEXTURE_RECTANGLE in GL 3.1 or GL_ARB_texture_rectangle or GL_NV_texture_rectangle
111
112OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily
113
114D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported)
115
116PIPE_TEXTURE_2D / PIPE_TEXTURE_2D_ARRAY
117^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1182D surface accessed with normalized coordinates.
1192D array textures are supported depending on PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS.
120
121- If PIPE_CAP_NPOT_TEXTURES is not supported,
122      width and height must be powers of two
123- depth0 must be 1
124- array_size must be 1 for PIPE_TEXTURE_2D
125- Mipmaps can be used
126- Must use normalized coordinates
127- No special restrictions on wrap modes
128
129OpenGL: GL_TEXTURE_2D in GL 1.0
130
131- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two
132
133OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily
134
135D3D11: 2D textures
136
137- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_9_3
138
139PIPE_TEXTURE_3D
140^^^^^^^^^^^^^^^
141
1423-dimensional array of texels.
143Mipmap dimensions are reduced in all 3 coordinates.
144
145- If PIPE_CAP_NPOT_TEXTURES is not supported,
146      width, height and depth must be powers of two
147- array_size must be 1
148- Must use normalized coordinates
149
150OpenGL: GL_TEXTURE_3D in GL 1.2 or GL_EXT_texture3D
151
152- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two
153
154D3D11: 3D textures
155
156- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0
157
158PIPE_TEXTURE_CUBE / PIPE_TEXTURE_CUBE_ARRAY
159^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
160
161Cube maps consist of 6 2D faces.
162The 6 surfaces form an imaginary cube, and sampling happens by mapping an
163input 3-vector to the point of the cube surface in that direction.
164Cube map arrays are supported depending on PIPE_CAP_CUBE_MAP_ARRAY.
165
166Sampling may be optionally seamless if a driver supports it (PIPE_CAP_SEAMLESS_CUBE_MAP),
167resulting in filtering taking samples from multiple surfaces near to the edge.
168
169- Width and height must be equal
170- depth0 must be 1
171- array_size must be a multiple of 6
172- If PIPE_CAP_NPOT_TEXTURES is not supported,
173      width and height must be powers of two
174- Must use normalized coordinates
175
176OpenGL: GL_TEXTURE_CUBE_MAP in GL 1.3 or EXT_texture_cube_map
177
178- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two
179- Seamless cube maps require GL 3.2 or GL_ARB_seamless_cube_map or GL_AMD_seamless_cubemap_per_texture
180- Cube map arrays require GL 4.0 or GL_ARB_texture_cube_map_array
181
182D3D11: 2D array textures with the D3D11_RESOURCE_MISC_TEXTURECUBE flag
183
184- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0
185- Cube map arrays require D3D_FEATURE_LEVEL_10_1
186
187Surfaces
188--------
189
190Surfaces are views of a resource that can be bound as a framebuffer to serve as the render target or depth buffer.
191
192TODO: write much more on surfaces
193
194OpenGL: FBOs are collections of surfaces in GL 3.0 or GL_ARB_framebuffer_object
195
196D3D11: render target views and depth/stencil views
197
198Sampler views
199-------------
200
201Sampler views are views of a resource that can be bound to a pipeline stage to be sampled from shaders.
202
203TODO: write much more on sampler views
204
205OpenGL: texture objects are actually sampler view and resource in a single unit
206
207D3D11: shader resource views
208