• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    ARB_compressed_texture_pixel_storage
4
5Name Strings
6
7    GL_ARB_compressed_texture_pixel_storage
8
9Contact
10
11    Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com)
12
13Contributors
14
15    Bruce Merry, ARM
16    Daniel Koch, TransGaming
17    Jeff Bolz, NVIDIA
18    Pat Brown, NVIDIA
19    Patrick Doane, Blizzard
20
21Notice
22
23    Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at
24        http://www.khronos.org/registry/speccopyright.html
25
26Specification Update Policy
27
28    Khronos-approved extension specifications are updated in response to
29    issues and bugs prioritized by the Khronos OpenGL Working Group. For
30    extensions which have been promoted to a core Specification, fixes will
31    first appear in the latest version of that core Specification, and will
32    eventually be backported to the extension document. This policy is
33    described in more detail at
34        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
35
36Status
37
38    Complete. Approved by the ARB on 2011/06/20.
39    Approved by the Khronos Promoters on 2011/07/29.
40
41Version
42
43    Last Modified Date:         April 26, 2011
44    Revision:                   8
45
46Number
47
48    ARB Extension #110
49
50Dependencies
51
52    OpenGL 1.2 is required.
53
54    This extension is written against The OpenGL 4.1 (Compatibility Profile)
55    specification.
56
57Overview
58
59    This extension expands the functionality of the PixelStore modes
60    to allow UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, UNPACK_SKIP_PIXELS,
61    UNPACK_IMAGE_HEIGHT and UNPACK_SKIP_IMAGES to affect the operation of
62    CompressedTexImage*D and CompressedTexSubImage*D. Similarly, it
63    also allows PACK_ROW_LENGTH, PACK_SKIP_ROWS, PACK_SKIP_PIXELS,
64    PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES to affect the operation of
65    GetCompressedTexImage*D. This allows data to be transferred
66    to or from a specified sub-rectangle of a larger compressed image.
67
68    This extension is designed primarily to support compressed image
69    formats with fixed-size blocks. To use this new mechanism, an
70    application should program new parameters UNPACK_COMPRESSED_BLOCK_
71    {WIDTH,HEIGHT,DEPTH,SIZE} to indicate the number of texels in each
72    dimension of the fixed-size block as well as the number of bytes
73    consumed by each block. These parameters, in addition to the
74    existing PixelStore parameters, are used to identify a collection
75    of bytes in client memory or a buffer object's data store to use
76    as compressed texture data. This operation is unlikely to have
77    the desired results if the client programs a block size inconsistent
78    with the underlying compressed image format, or if the compressed
79    image format has variable-sized blocks.
80
81New Procedures and Functions
82
83    None
84
85New Tokens
86
87    Accepted by the <pname> parameter of PixelStore[fi], GetBooleanv,
88    GetIntegerv, GetInteger64v, GetFloatv, and GetDoublev:
89
90        UNPACK_COMPRESSED_BLOCK_WIDTH                    0x9127
91        UNPACK_COMPRESSED_BLOCK_HEIGHT                   0x9128
92        UNPACK_COMPRESSED_BLOCK_DEPTH                    0x9129
93        UNPACK_COMPRESSED_BLOCK_SIZE                     0x912A
94        PACK_COMPRESSED_BLOCK_WIDTH                      0x912B
95        PACK_COMPRESSED_BLOCK_HEIGHT                     0x912C
96        PACK_COMPRESSED_BLOCK_DEPTH                      0x912D
97        PACK_COMPRESSED_BLOCK_SIZE                       0x912E
98
99Changes to Section 3.7.4 (Pixel Storage Modes and Pixel Buffer Objects),
100page 229
101
102    Replace the section in the first paragraph, page 229 that states:
103
104    "Pixel storage modes affect the operation of TexImage*D, TexSubImage*D,
105    DrawPixels, and ReadPixels (as well as other commands; see sections 3.6.2
106    and 3.8) when one of these commands is issued."
107
108    With the following:
109
110    "Pixel storage modes affect the operation of TexImage*D, TexSubImage*D,
111    CompressedTexImage*D, CompressedTexSubImage*d, DrawPixels, and ReadPixels
112    (as well as other commands; see sections 3.6.2 and 3.8) when one of these
113    commands is issued."
114
115    Modify Table 3.1 description to:
116
117    "Table 3.1: PixelStore parameters pertaining to one or more of
118    DrawPixels, ColorTable, ColorSubTable, ConvolutionFilter1D,
119    ConvolutionFilter2D, SeparableFilter2D, PolygonStipple, TexImage1D,
120    TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, TexSubImage3D,
121    CompressedTexImage1D, CompressedTexImage2D, CompressedTexImage3D,
122    CompressedTexSubImage1D, CompressedTexSubImage2D and
123    CompressedTexSubImage3D."
124
125    Add to Table 3.1 contents with the following new entries:
126
127    Parameter Name                   Type   Initial Value  Valid Range
128    -------------------------------------------------------------------------
129    UNPACK_COMPRESSED_BLOCK_WIDTH   integer       0         [0,inf)
130    UNPACK_COMPRESSED_BLOCK_HEIGHT  integer       0         [0,inf)
131    UNPACK_COMPRESSED_BLOCK_DEPTH   integer       0         [0,inf)
132    UNPACK_COMPRESSED_BLOCK_SIZE    integer       0         [0,inf)
133
134Changes to Section 3.9.5 (Compressed Texture Images), page 297
135
136    In the paragraph that starts "For all other compressed internal
137    formats..." remove the following sentence:
138
139    "All pixel storage and pixel transfer modes are ignored when decoding a
140    compressed texture image."
141
142    Add a new paragraph which states:
143
144    "If the compressed data are arranged into fixed-size blocks of texels the
145    pixel storage modes can be used to select a sub-rectangle from a larger
146    containing rectangle. These pixel storage modes operate in the same
147    way as they do for TexImage*D and as described in section 3.7.4. By
148    default the pixel storage modes UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS,
149    UNPACK_SKIP_PIXELS, UNPACK_IMAGE_HEIGHT and UNPACK_SKIP_IMAGES are
150    ignored for compressed images. To enable UNPACK_SKIP_PIXELS and
151    UNPACK_ROW_LENGTH both UNPACK_COMPRESSED_BLOCK_SIZE and
152    UNPACK_COMPRESSED_BLOCK_WIDTH must be non-zero. To also enable
153    UNPACK_SKIP_ROWS and UNPACK_IMAGE_HEIGHT, UNPACK_COMPRESSED_BLOCK_HEIGHT
154    must be non-zero. And to also enable UNPACK_SKIP_IMAGES,
155    UNPACK_COMPRESSED_BLOCK_DEPTH must be non-zero. Use
156    UNPACK_COMPRESSED_BLOCK_WIDTH to specify the block width in pixels,
157    UNPACK_COMPRESSED_BLOCK_HEIGHT to specify the block height in pixels,
158    UNPACK_COMPRESSED_BLOCK_DEPTH to specify the block depth in pixels and
159    UNPACK_COMPRESSED_BLOCK_SIZE to specify the block size in bytes. All
160    parameters need to be consistent with the compressed format to produce
161    the desired results.
162
163    When selecting a sub-rectangle from a compressed image:
164
165    * the UNPACK_SKIP_PIXELS parameter must be a multiple of the
166      UNPACK_COMPRESSED_BLOCK_WIDTH parameter;
167    * the UNPACK_SKIP_ROWS parameter must be a multiple of the
168      UNPACK_COMPRESSED_BLOCK_HEIGHT parameter for CompressedTexImage2D
169      and CompressedTexImage3D;
170    * the UNPACK_SKIP_IMAGES parameter must be a multiple of the
171      UNPACK_COMPRESSED_BLOCK_DEPTH parameter for CompressedTexImage3D.
172
173    The error INVALID_OPERATION will be generated if any of the previous
174    conditions are violated.
175
176    For CompressedTexImage1D the <imageSize> parameter must be equal to:
177        UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH)
178    For CompressedTexImage2D the <imageSize> parameter must be equal to:
179        UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) * ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT)
180    For CompressedTexImage3D the <imageSize> parameter must be equal to:
181        UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) * ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT) * ceil(<depth> / UNPACK_COMPRESSED_BLOCK_DEPTH)
182
183    The error INVALID_VALUE will be generated if <imageSize> does not match
184    this requirement when pixel storage modes are active.
185
186    Based on the definition of Unpacking from Section 3.7.4 for uncompressed
187    images, unpacking compressed images can be defined where:
188
189    * "n", the number of elements in a group, is 1
190    * "s", the size of an element, is UNPACK_COMPRESSED_BLOCK_SIZE
191    * "l", the number of groups in a row, is ceil(UNPACK_ROW_LENGTH /
192      UNPACK_COMPRESSED_BLOCK_WIDTH), where UNPACK_ROW_LENGTH is positive
193      otherwise it's ceil(<length> / UNPACK_COMPRESSED_BLOCK_WIDTH)
194    * "a", the value of UNPACK_ALIGNMENT is ignored and
195    * "k=nl" as is defined for uncompressed images.
196
197    Before obtaining the first compressed image block from memory, the <data>
198    pointer is advanced by (UNPACK_SKIP_PIXELS /
199    UNPACK_COMPRESSED_BLOCK_WIDTH) * "n" + (UNPACK_SKIP_ROWS /
200    UNPACK_COMPRESSED_BLOCK_HEIGHT) * "k" elements. Then ceil(<width> /
201    UNPACK_COMPRESSED_BLOCK_WIDTH) blocks are obtained from contiguous blocks
202    in memory (without advancing the pointer), after which the pointer is
203    advanced by "k" elements. ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT)
204    sets of ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) blocks are obtained
205    this way. For three-dimensional compressed images the pointer is advanced
206    by (UNPACK_SKIP_IMAGES / UNPACK_COMPRESSED_BLOCK_DEPTH) times the number
207    of elements in one two-dimensional image before obtaining the first group
208    from memory. Then after <height> rows are obtained the pointer skips over
209    the remaining ceil(UNPACK_IMAGE_HEIGHT / UNPACK_COMPRESSED_BLOCK_HEIGHT)
210    rows, if UNPACK_IMAGE_HEIGHT is positive before starting the next two-
211    dimensional image."
212
213Changes to Section 4.3.2 (Reading Pixels), page 380
214
215    Modify Table 4.7, page 382, description to:
216
217    "Table 4.7: PixelStore parameters pertaining to ReadPixels,
218    GetColorTable, GetConvolutionFilter, GetSeparableFilter, GetHistogram,
219    GetMinmax, GetPolygonStipple, GetTexImage, and GetCompressedTexImage."
220
221    Add to Table 4.7 contents with the following new entries:
222
223    Parameter Name                Type    Initial Value  Valid Range
224    -------------------------------------------------------------------------
225    PACK_COMPRESSED_BLOCK_WIDTH   integer       0         [0,inf)
226    PACK_COMPRESSED_BLOCK_HEIGHT  integer       0         [0,inf)
227    PACK_COMPRESSED_BLOCK_DEPTH   integer       0         [0,inf)
228    PACK_COMPRESSED_BLOCK_SIZE    integer       0         [0,inf)
229
230Changes to Section 6.1.4 (Texture Queries), page 446
231
232    In the paragraph that talks about GetCompressedTexImage remove the
233    following sentence:
234
235    "All pixel storage and pixel transfer modes are ignored when returning a
236    compressed texture image."
237
238    Add a new paragraph at this point with the following contents:
239
240    "By default the pixel storage modes PACK_ROW_LENGTH, PACK_SKIP_ROWS,
241    PACK_SKIP_PIXELS, PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES are ignored for
242    compressed images. To enable PACK_SKIP_PIXELS and PACK_ROW_LENGTH both
243    PACK_COMPRESSED_BLOCK_SIZE and PACK_COMPRESSED_BLOCK_WIDTH must be non-
244    zero. To also enable PACK_SKIP_ROWS and PACK_IMAGE_HEIGHT,
245    PACK_COMPRESSED_BLOCK_HEIGHT must be non-zero. And to also enable
246    PACK_SKIP_IMAGES, PACK_COMPRESSED_BLOCK_DEPTH must be non-zero. All
247    parameters need to be consistent with the compressed format to produce
248    the desired results. When the pixel storage modes are active, the
249    correspondence of texels to memory locations is as defined for
250    CompressedTexImage3D in section 3.9.5."
251
252Additions to the AGL/GLX/WGL Specifications
253
254    None
255
256Errors
257
258    None
259
260New State
261
262    (Table 6.37, Pixels) add the following:
263
264    Get Value                       Type  Get Command      Initial Value  Description                             Section
265    -------------                   ----  -----------      -------------  -----------                             -------
266    UNPACK_COMPRESSED_BLOCK_WIDTH   Z+    GetIntegerv      0              Value of UNPACK_COMPRESSED_BLOCK_WIDTH  3.7.4
267    UNPACK_COMPRESSED_BLOCK_HEIGHT  Z+    GetIntegerv      0              Value of UNPACK_COMPRESSED_BLOCK_HEIGHT 3.7.4
268    UNPACK_COMPRESSED_BLOCK_DEPTH   Z+    GetIntegerv      0              Value of UNPACK_COMPRESSED_BLOCK_DEPTH  3.7.4
269    UNPACK_COMPRESSED_BLOCK_SIZE    Z+    GetIntegerv      0              Value of UNPACK_COMPRESSED_BLOCK_SIZE   3.7.4
270    PACK_COMPRESSED_BLOCK_WIDTH     Z+    GetIntegerv      0              Value of PACK_COMPRESSED_BLOCK_WIDTH    4.3.2
271    PACK_COMPRESSED_BLOCK_HEIGHT    Z+    GetIntegerv      0              Value of PACK_COMPRESSED_BLOCK_HEIGHT   4.3.2
272    PACK_COMPRESSED_BLOCK_DEPTH     Z+    GetIntegerv      0              Value of PACK_COMPRESSED_BLOCK_DEPTH    4.3.2
273    PACK_COMPRESSED_BLOCK_SIZE      Z+    GetIntegerv      0              Value of PACK_COMPRESSED_BLOCK_SIZE     4.3.2
274
275New Implementation Dependent State
276
277    None
278
279Issues
280
281    1) How do indirect rendering implementations deal with this? They don't
282       know what compressed format is used.
283
284       RESOLVED: By specifying the BLOCK sizes in the PixelStore parameters
285       the client side implementation has enough information to transfer the
286       minimal amount of data to satisfy the API request without needing
287       detailed knowledge of the compression format. So from the client
288       to server data transfer point of view, it's still just a memcpy of
289       the client data without interpretation based on the compression
290       format.
291
292    2) Do we enforce that the block size parameters match those of the format
293       being manipulated?
294
295       RESOLVED: No. They are only used for this memcpy operation. The
296       issue is that PixelStore is client state, while the actual format of
297       the texture is server state that may not even be knowable by the
298       client. If the user indicates that he is dealing in 8x2 64-bit blocks,
299       the client may not be able to figure out that it doesn't accurately
300       describe the actual format (e.g., DXT1 using 4x4 64-bit blocks).
301
302       However, we don't really care. These parameters are used (along with
303       the API call parameters) to indicate a collection of bytes to read.
304       The client extracts those bytes and transfers them to the server for
305       further processing. If the byte count isn't consistent with the
306       width/height/internalformat parameters, the server complains. If the
307       byte count is consistent, the server just accepts the data extracted
308       by the client as-is.
309
310       For example, let's say we specified a 16x16 DXT1 image. That would
311       have the server looking for a 4x4 array of blocks (128B total). If
312       the user said the blocks were 8x2 and 64-bit, the client would
313       transmit a 2x8 array of blocks (still 128B). We'd get no error.
314       However, if the image were 12x12, the server would want a 3x3 array
315       of blocks, while the client would want to transmit a 2x6 array of
316       blocks because the rightmost "8x2" blocks are partial and would be
317       padded out as though the image were 16x12. In that case, the byte
318       counts wouldn't be consistent.
319
320    3) Do we need to specify what happens with a hypothetical variable-size
321       block format?
322
323       RESOLVED: These new "block size" parameters are used to collect
324       scattered bytes from user memory into a single block of "sub image"
325       memory, and they don't care what the format is.
326
327    4) Do these new parameters affect TexImage* calls with compressed internal
328       formats?
329
330       RESOLVED:  No, they only affect CompressedTexImage*,
331       CompressedTexSubImage* and GetCompressedTexImage* APIs, where the
332       texels specified or queried are specified or returned in compressed
333       form. In desktop OpenGL, it is possible to specify or query texels for
334       textures with compressed internal formats using APIs like TexImage*,
335       using non-compressed <format> and <type> arguments. In these cases,
336       previously existing PixelStore parameters already applied to the
337       specified image.
338
339    5) Should {UN}PACK_ROW_LENGTH and {UN}PACK_IMAGE_HEIGHT be required to be
340       in multiples of the block size?
341
342       RESOLVED: It's not necessary since the rounding in the specified
343       compressed image unpacking will round up to the next block size and
344       produce a valid result.
345
346Revision History
347
348    Rev.    Date    Author    Changes
349    ----  --------  --------  -----------------------------------------------
350    8     04/26/11  pdaniell  Fix language which specifies what parameters
351                              need to be non-zero for {UN}PACK_IMAGE_HEIGHT
352                              to be used.
353
354    7     04/21/11  pdaniell  Add final enum values.
355
356    6     12/15/10  pdaniell  Resolve issues 2 and 5.
357
358    5     11/29/10  pdaniell  Fix typo.
359
360    4     11/10/10  pdaniell  Fixes based on feedback from Bruce and Pat in
361                              bug 7016.
362
363    3     11/05/10  pdaniell  Resolve issue (2).
364
365    2     11/04/10  pdaniell  Fixed typos and feedback from bug 6998.
366                              Moved edits from Core to Compatibility profile.
367                              Further clarifications from internal review.
368
369    1     10/19/10  pdaniell  Initial version.
370