← Back to branch summary

~ubuntu-branches/ubuntu/precise/mesa/precise-updates

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Christopher James Halse Rogers
  • Date: 2011-08-04 16:25:08 UTC
  • mfrom: (1.2.37 upstream)
  • Revision ID: james.westby@ubuntu.com-20110804162508-kujg82moxerjg1kk
Tags: 7.11-0ubuntu1
https://launchpad.net/bugs/800778
https://launchpad.net/bugs/812639
https://launchpad.net/bugs/810339
https://launchpad.net/bugs/410264
* Fake merge from Debian experimental, updating previous changelog entries.
  New upstream release fixes infrequent X crash (LP: #800778).
  Remaining Ubuntu changes:
 - debian/control
    + Drop lesstif-dev from Build-Depends; it's in Universe.
    + Comment out GLw libs since it depends on lesstif-dev.
    + Drop i686 swx11 libgl package.
    + Add libdrm-dev to mesa-common-dev Depends.
    + Drop libwayland-dev from Build-Depends; it's in Universe.
    + Update Breaks for Ubuntu versions
    + Enable llvm on armel as well as i386 and amd64
  - debian/rules
    + Use --disable-glw for swx11 targets too.
    + Don't enable motif for swx11 targets.
    + Use lzma compression for binary debs to save CD space.
    + Drop unloved mach64 driver.
    + Use --enable-shared-dricore to claw back CD space.
    + Enable llvmpipe software rasteriser.
    + Enable llvm on armel as well as i386 and amd64
  - debian/patches
    + 100_no_abi_tag.patch
    + 101_ubuntu_hidden_glname.patch
    + 103_savage-expose_fbmodes_with_nonzero_alpha.patch
  - rules, libgl1-mesa-{glx,dev,swx11,swx11-dev}.install.in,
    libgl1-mesa-{glx,swx11}.{postinst,prerm}.in, libgl1-mesa-dev.links.in:
    Install libGL.so* in /usr/lib/mesa to allow things to work with
    alternatives.
  - debian/not-installed:
    + Drop i686 files; we don't build 686-optimised packages in the first
      place.
  - debian/gbp.conf
    + Point at Ubuntu branch to make git-buildpackage less narky.
  - 113_fix_tls.diff: Fix crashes in unrelated code due to TLS usage.
  - debian/patches/111_export_searchdirs_in_dripc.diff:
    + Add drisearchdirs variable to dri.pc so the Xserver can pick up the
      alternate DRI driver dirs.
  - debian/patches/115_llvm_dynamic_linking.diff
    + Dynamically link DRI drivers to libllvm.  Saves ~6MiB per DRI driver.
  - debian/patches/116_use_shared_galliumcore.diff:
  - debian/libgl1-mesa-dri.install.in:
    + Link gallium DRI drivers against shared gallium routines to save CD
      space.
* debian/rules:
* debian/libgl1-mesa-dri-experimental.install.{i386,amd64}.in
  - Explicitly install i915g only when it has been built, matching what is
    done with r300g.
* debian/rules:
* debian/control:
* debian/libegl1-mesa{,-dev}.install.in:
* debian/libegl1-mesa.symbols:
  - Enable the Wayland EGL backend.
* debian/rules:
* debian/libegl1-mesa.{postinst,prerm,install}.in:
* debian/libegl1-mesa-dev.{install,links}.in:
* debian/libgles{1,2}-mesa.install.in:
* debian/libgles{1,2}-mesa-dev.links.in:
* debian/libopenvg1-mesa{,-dev}.install.in:
* debian/libopenvg1-mesa-dev.links.in:
  - Use alternatives for libEGL to match the handling of libGL.
    libEGL (and associated GL|ES and OpenVG libraries) now live in
    /usr/lib/$MULTIARCH/mesa-egl.  (LP: #812639)
* debian/patches/118_fix_24bpp_software_rendering.diff:
  - Cherry pick upstream patch from master fixing graphical corruption when
    using a 24bpp framebuffer and software rendering. (LP: #810339)
* debian/rules:
* debian/clean:
  - Generate xmlpool pot file and clean up other po files for
    pkgbinarymangler's benefit (LP: #410264).
* debian/patches/119_r600g_gnome_shell_rendering_fix.diff:
  - Cherry pick upstream commit fixing rendering corruption in gnome-shell
    (and therefore likely Unity as well).

Show diffs side-by-side

added added

removed removed

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