← Back to branch summary

~ubuntu-branches/ubuntu/trusty/mesa-lts-utopic/trusty-proposed

« back to all changes in this revision

Viewing changes to src/gallium/docs/source/resources.rst

  • Committer: Package Import Robot
  • Author(s): Maarten Lankhorst
  • Date: 2015-01-06 10:38:32 UTC
  • Revision ID: package-import@ubuntu.com-20150106103832-u6rqp9wfmojb1gnu
Tags: upstream-10.3.2
Import upstream version 10.3.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/gallium/docs/source/resources.rst
 
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_CAP_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 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
 
 
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_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
 
 
94
OpenGL: 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
 
 
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 GL_ARB_texture_rectangle or GL_NV_texture_rectangle
 
111
 
 
112
OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily
 
113
 
 
114
D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported)
 
115
 
 
116
PIPE_TEXTURE_2D / PIPE_TEXTURE_2D_ARRAY
 
117
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
118
2D surface accessed with normalized coordinates.
 
119
2D 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
 
 
129
OpenGL: 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
 
 
133
OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily
 
134
 
 
135
D3D11: 2D textures
 
136
 
 
137
- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_9_3
 
138
 
 
139
PIPE_TEXTURE_3D
 
140
^^^^^^^^^^^^^^^
 
141
 
 
142
3-dimensional array of texels.
 
143
Mipmap 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
 
 
150
OpenGL: 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
 
 
154
D3D11: 3D textures
 
155
 
 
156
- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0
 
157
 
 
158
PIPE_TEXTURE_CUBE / PIPE_TEXTURE_CUBE_ARRAY
 
159
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
160
 
 
161
Cube maps consist of 6 2D faces.
 
162
The 6 surfaces form an imaginary cube, and sampling happens by mapping an
 
163
input 3-vector to the point of the cube surface in that direction.
 
164
Cube map arrays are supported depending on PIPE_CAP_CUBE_MAP_ARRAY.
 
165
 
 
166
Sampling may be optionally seamless if a driver supports it (PIPE_CAP_SEAMLESS_CUBE_MAP),
 
167
resulting 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
 
 
176
OpenGL: 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
 
 
182
D3D11: 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
 
 
187
Surfaces
 
188
--------
 
189
 
 
190
Surfaces are views of a resource that can be bound as a framebuffer to serve as the render target or depth buffer.
 
191
 
 
192
TODO: write much more on surfaces
 
193
 
 
194
OpenGL: FBOs are collections of surfaces in GL 3.0 or GL_ARB_framebuffer_object
 
195
 
 
196
D3D11: render target views and depth/stencil views
 
197
 
 
198
Sampler views
 
199
-------------
 
200
 
 
201
Sampler views are views of a resource that can be bound to a pipeline stage to be sampled from shaders.
 
202
 
 
203
TODO: write much more on sampler views
 
204
 
 
205
OpenGL: texture objects are actually sampler view and resource in a single unit
 
206
 
 
207
D3D11: shader resource views