Debian Codegraph @

docs/gallium/resources.rst

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