blob: 6fb04f3167381d930af226586619631e999e0159 [file] [log] [blame]
Name
ARB_compressed_texture_pixel_storage
Name Strings
GL_ARB_compressed_texture_pixel_storage
Contact
Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com)
Contributors
Bruce Merry, ARM
Daniel Koch, TransGaming
Jeff Bolz, NVIDIA
Pat Brown, NVIDIA
Patrick Doane, Blizzard
Notice
Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Specification Update Policy
Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
https://www.khronos.org/registry/OpenGL/docs/update_policy.php
Status
Complete. Approved by the ARB on 2011/06/20.
Approved by the Khronos Promoters on 2011/07/29.
Version
Last Modified Date: April 26, 2011
Revision: 8
Number
ARB Extension #110
Dependencies
OpenGL 1.2 is required.
This extension is written against The OpenGL 4.1 (Compatibility Profile)
specification.
Overview
This extension expands the functionality of the PixelStore modes
to allow UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS, UNPACK_SKIP_PIXELS,
UNPACK_IMAGE_HEIGHT and UNPACK_SKIP_IMAGES to affect the operation of
CompressedTexImage*D and CompressedTexSubImage*D. Similarly, it
also allows PACK_ROW_LENGTH, PACK_SKIP_ROWS, PACK_SKIP_PIXELS,
PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES to affect the operation of
GetCompressedTexImage*D. This allows data to be transferred
to or from a specified sub-rectangle of a larger compressed image.
This extension is designed primarily to support compressed image
formats with fixed-size blocks. To use this new mechanism, an
application should program new parameters UNPACK_COMPRESSED_BLOCK_
{WIDTH,HEIGHT,DEPTH,SIZE} to indicate the number of texels in each
dimension of the fixed-size block as well as the number of bytes
consumed by each block. These parameters, in addition to the
existing PixelStore parameters, are used to identify a collection
of bytes in client memory or a buffer object's data store to use
as compressed texture data. This operation is unlikely to have
the desired results if the client programs a block size inconsistent
with the underlying compressed image format, or if the compressed
image format has variable-sized blocks.
New Procedures and Functions
None
New Tokens
Accepted by the <pname> parameter of PixelStore[fi], GetBooleanv,
GetIntegerv, GetInteger64v, GetFloatv, and GetDoublev:
UNPACK_COMPRESSED_BLOCK_WIDTH 0x9127
UNPACK_COMPRESSED_BLOCK_HEIGHT 0x9128
UNPACK_COMPRESSED_BLOCK_DEPTH 0x9129
UNPACK_COMPRESSED_BLOCK_SIZE 0x912A
PACK_COMPRESSED_BLOCK_WIDTH 0x912B
PACK_COMPRESSED_BLOCK_HEIGHT 0x912C
PACK_COMPRESSED_BLOCK_DEPTH 0x912D
PACK_COMPRESSED_BLOCK_SIZE 0x912E
Changes to Section 3.7.4 (Pixel Storage Modes and Pixel Buffer Objects),
page 229
Replace the section in the first paragraph, page 229 that states:
"Pixel storage modes affect the operation of TexImage*D, TexSubImage*D,
DrawPixels, and ReadPixels (as well as other commands; see sections 3.6.2
and 3.8) when one of these commands is issued."
With the following:
"Pixel storage modes affect the operation of TexImage*D, TexSubImage*D,
CompressedTexImage*D, CompressedTexSubImage*d, DrawPixels, and ReadPixels
(as well as other commands; see sections 3.6.2 and 3.8) when one of these
commands is issued."
Modify Table 3.1 description to:
"Table 3.1: PixelStore parameters pertaining to one or more of
DrawPixels, ColorTable, ColorSubTable, ConvolutionFilter1D,
ConvolutionFilter2D, SeparableFilter2D, PolygonStipple, TexImage1D,
TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, TexSubImage3D,
CompressedTexImage1D, CompressedTexImage2D, CompressedTexImage3D,
CompressedTexSubImage1D, CompressedTexSubImage2D and
CompressedTexSubImage3D."
Add to Table 3.1 contents with the following new entries:
Parameter Name Type Initial Value Valid Range
-------------------------------------------------------------------------
UNPACK_COMPRESSED_BLOCK_WIDTH integer 0 [0,inf)
UNPACK_COMPRESSED_BLOCK_HEIGHT integer 0 [0,inf)
UNPACK_COMPRESSED_BLOCK_DEPTH integer 0 [0,inf)
UNPACK_COMPRESSED_BLOCK_SIZE integer 0 [0,inf)
Changes to Section 3.9.5 (Compressed Texture Images), page 297
In the paragraph that starts "For all other compressed internal
formats..." remove the following sentence:
"All pixel storage and pixel transfer modes are ignored when decoding a
compressed texture image."
Add a new paragraph which states:
"If the compressed data are arranged into fixed-size blocks of texels the
pixel storage modes can be used to select a sub-rectangle from a larger
containing rectangle. These pixel storage modes operate in the same
way as they do for TexImage*D and as described in section 3.7.4. By
default the pixel storage modes UNPACK_ROW_LENGTH, UNPACK_SKIP_ROWS,
UNPACK_SKIP_PIXELS, UNPACK_IMAGE_HEIGHT and UNPACK_SKIP_IMAGES are
ignored for compressed images. To enable UNPACK_SKIP_PIXELS and
UNPACK_ROW_LENGTH both UNPACK_COMPRESSED_BLOCK_SIZE and
UNPACK_COMPRESSED_BLOCK_WIDTH must be non-zero. To also enable
UNPACK_SKIP_ROWS and UNPACK_IMAGE_HEIGHT, UNPACK_COMPRESSED_BLOCK_HEIGHT
must be non-zero. And to also enable UNPACK_SKIP_IMAGES,
UNPACK_COMPRESSED_BLOCK_DEPTH must be non-zero. Use
UNPACK_COMPRESSED_BLOCK_WIDTH to specify the block width in pixels,
UNPACK_COMPRESSED_BLOCK_HEIGHT to specify the block height in pixels,
UNPACK_COMPRESSED_BLOCK_DEPTH to specify the block depth in pixels and
UNPACK_COMPRESSED_BLOCK_SIZE to specify the block size in bytes. All
parameters need to be consistent with the compressed format to produce
the desired results.
When selecting a sub-rectangle from a compressed image:
* the UNPACK_SKIP_PIXELS parameter must be a multiple of the
UNPACK_COMPRESSED_BLOCK_WIDTH parameter;
* the UNPACK_SKIP_ROWS parameter must be a multiple of the
UNPACK_COMPRESSED_BLOCK_HEIGHT parameter for CompressedTexImage2D
and CompressedTexImage3D;
* the UNPACK_SKIP_IMAGES parameter must be a multiple of the
UNPACK_COMPRESSED_BLOCK_DEPTH parameter for CompressedTexImage3D.
The error INVALID_OPERATION will be generated if any of the previous
conditions are violated.
For CompressedTexImage1D the <imageSize> parameter must be equal to:
UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH)
For CompressedTexImage2D the <imageSize> parameter must be equal to:
UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) * ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT)
For CompressedTexImage3D the <imageSize> parameter must be equal to:
UNPACK_COMPRESSED_BLOCK_SIZE * ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) * ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT) * ceil(<depth> / UNPACK_COMPRESSED_BLOCK_DEPTH)
The error INVALID_VALUE will be generated if <imageSize> does not match
this requirement when pixel storage modes are active.
Based on the definition of Unpacking from Section 3.7.4 for uncompressed
images, unpacking compressed images can be defined where:
* "n", the number of elements in a group, is 1
* "s", the size of an element, is UNPACK_COMPRESSED_BLOCK_SIZE
* "l", the number of groups in a row, is ceil(UNPACK_ROW_LENGTH /
UNPACK_COMPRESSED_BLOCK_WIDTH), where UNPACK_ROW_LENGTH is positive
otherwise it's ceil(<length> / UNPACK_COMPRESSED_BLOCK_WIDTH)
* "a", the value of UNPACK_ALIGNMENT is ignored and
* "k=nl" as is defined for uncompressed images.
Before obtaining the first compressed image block from memory, the <data>
pointer is advanced by (UNPACK_SKIP_PIXELS /
UNPACK_COMPRESSED_BLOCK_WIDTH) * "n" + (UNPACK_SKIP_ROWS /
UNPACK_COMPRESSED_BLOCK_HEIGHT) * "k" elements. Then ceil(<width> /
UNPACK_COMPRESSED_BLOCK_WIDTH) blocks are obtained from contiguous blocks
in memory (without advancing the pointer), after which the pointer is
advanced by "k" elements. ceil(<height> / UNPACK_COMPRESSED_BLOCK_HEIGHT)
sets of ceil(<width> / UNPACK_COMPRESSED_BLOCK_WIDTH) blocks are obtained
this way. For three-dimensional compressed images the pointer is advanced
by (UNPACK_SKIP_IMAGES / UNPACK_COMPRESSED_BLOCK_DEPTH) times the number
of elements in one two-dimensional image before obtaining the first group
from memory. Then after <height> rows are obtained the pointer skips over
the remaining ceil(UNPACK_IMAGE_HEIGHT / UNPACK_COMPRESSED_BLOCK_HEIGHT)
rows, if UNPACK_IMAGE_HEIGHT is positive before starting the next two-
dimensional image."
Changes to Section 4.3.2 (Reading Pixels), page 380
Modify Table 4.7, page 382, description to:
"Table 4.7: PixelStore parameters pertaining to ReadPixels,
GetColorTable, GetConvolutionFilter, GetSeparableFilter, GetHistogram,
GetMinmax, GetPolygonStipple, GetTexImage, and GetCompressedTexImage."
Add to Table 4.7 contents with the following new entries:
Parameter Name Type Initial Value Valid Range
-------------------------------------------------------------------------
PACK_COMPRESSED_BLOCK_WIDTH integer 0 [0,inf)
PACK_COMPRESSED_BLOCK_HEIGHT integer 0 [0,inf)
PACK_COMPRESSED_BLOCK_DEPTH integer 0 [0,inf)
PACK_COMPRESSED_BLOCK_SIZE integer 0 [0,inf)
Changes to Section 6.1.4 (Texture Queries), page 446
In the paragraph that talks about GetCompressedTexImage remove the
following sentence:
"All pixel storage and pixel transfer modes are ignored when returning a
compressed texture image."
Add a new paragraph at this point with the following contents:
"By default the pixel storage modes PACK_ROW_LENGTH, PACK_SKIP_ROWS,
PACK_SKIP_PIXELS, PACK_IMAGE_HEIGHT and PACK_SKIP_IMAGES are ignored for
compressed images. To enable PACK_SKIP_PIXELS and PACK_ROW_LENGTH both
PACK_COMPRESSED_BLOCK_SIZE and PACK_COMPRESSED_BLOCK_WIDTH must be non-
zero. To also enable PACK_SKIP_ROWS and PACK_IMAGE_HEIGHT,
PACK_COMPRESSED_BLOCK_HEIGHT must be non-zero. And to also enable
PACK_SKIP_IMAGES, PACK_COMPRESSED_BLOCK_DEPTH must be non-zero. All
parameters need to be consistent with the compressed format to produce
the desired results. When the pixel storage modes are active, the
correspondence of texels to memory locations is as defined for
CompressedTexImage3D in section 3.9.5."
Additions to the AGL/GLX/WGL Specifications
None
Errors
None
New State
(Table 6.37, Pixels) add the following:
Get Value Type Get Command Initial Value Description Section
------------- ---- ----------- ------------- ----------- -------
UNPACK_COMPRESSED_BLOCK_WIDTH Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_WIDTH 3.7.4
UNPACK_COMPRESSED_BLOCK_HEIGHT Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_HEIGHT 3.7.4
UNPACK_COMPRESSED_BLOCK_DEPTH Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_DEPTH 3.7.4
UNPACK_COMPRESSED_BLOCK_SIZE Z+ GetIntegerv 0 Value of UNPACK_COMPRESSED_BLOCK_SIZE 3.7.4
PACK_COMPRESSED_BLOCK_WIDTH Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_WIDTH 4.3.2
PACK_COMPRESSED_BLOCK_HEIGHT Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_HEIGHT 4.3.2
PACK_COMPRESSED_BLOCK_DEPTH Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_DEPTH 4.3.2
PACK_COMPRESSED_BLOCK_SIZE Z+ GetIntegerv 0 Value of PACK_COMPRESSED_BLOCK_SIZE 4.3.2
New Implementation Dependent State
None
Issues
1) How do indirect rendering implementations deal with this? They don't
know what compressed format is used.
RESOLVED: By specifying the BLOCK sizes in the PixelStore parameters
the client side implementation has enough information to transfer the
minimal amount of data to satisfy the API request without needing
detailed knowledge of the compression format. So from the client
to server data transfer point of view, it's still just a memcpy of
the client data without interpretation based on the compression
format.
2) Do we enforce that the block size parameters match those of the format
being manipulated?
RESOLVED: No. They are only used for this memcpy operation. The
issue is that PixelStore is client state, while the actual format of
the texture is server state that may not even be knowable by the
client. If the user indicates that he is dealing in 8x2 64-bit blocks,
the client may not be able to figure out that it doesn't accurately
describe the actual format (e.g., DXT1 using 4x4 64-bit blocks).
However, we don't really care. These parameters are used (along with
the API call parameters) to indicate a collection of bytes to read.
The client extracts those bytes and transfers them to the server for
further processing. If the byte count isn't consistent with the
width/height/internalformat parameters, the server complains. If the
byte count is consistent, the server just accepts the data extracted
by the client as-is.
For example, let's say we specified a 16x16 DXT1 image. That would
have the server looking for a 4x4 array of blocks (128B total). If
the user said the blocks were 8x2 and 64-bit, the client would
transmit a 2x8 array of blocks (still 128B). We'd get no error.
However, if the image were 12x12, the server would want a 3x3 array
of blocks, while the client would want to transmit a 2x6 array of
blocks because the rightmost "8x2" blocks are partial and would be
padded out as though the image were 16x12. In that case, the byte
counts wouldn't be consistent.
3) Do we need to specify what happens with a hypothetical variable-size
block format?
RESOLVED: These new "block size" parameters are used to collect
scattered bytes from user memory into a single block of "sub image"
memory, and they don't care what the format is.
4) Do these new parameters affect TexImage* calls with compressed internal
formats?
RESOLVED: No, they only affect CompressedTexImage*,
CompressedTexSubImage* and GetCompressedTexImage* APIs, where the
texels specified or queried are specified or returned in compressed
form. In desktop OpenGL, it is possible to specify or query texels for
textures with compressed internal formats using APIs like TexImage*,
using non-compressed <format> and <type> arguments. In these cases,
previously existing PixelStore parameters already applied to the
specified image.
5) Should {UN}PACK_ROW_LENGTH and {UN}PACK_IMAGE_HEIGHT be required to be
in multiples of the block size?
RESOLVED: It's not necessary since the rounding in the specified
compressed image unpacking will round up to the next block size and
produce a valid result.
Revision History
Rev. Date Author Changes
---- -------- -------- -----------------------------------------------
8 04/26/11 pdaniell Fix language which specifies what parameters
need to be non-zero for {UN}PACK_IMAGE_HEIGHT
to be used.
7 04/21/11 pdaniell Add final enum values.
6 12/15/10 pdaniell Resolve issues 2 and 5.
5 11/29/10 pdaniell Fix typo.
4 11/10/10 pdaniell Fixes based on feedback from Bruce and Pat in
bug 7016.
3 11/05/10 pdaniell Resolve issue (2).
2 11/04/10 pdaniell Fixed typos and feedback from bug 6998.
Moved edits from Core to Compatibility profile.
Further clarifications from internal review.
1 10/19/10 pdaniell Initial version.