Back to the OpenGL extension cross reference
GL_APPLE_client_storage
APPLE_client_storage
Name Strings
GL_APPLE_client_storage
Contact
Geoff Stahl, Apple (gstahl 'at' apple.com)
Status
Complete
Version
$Date: 2002/08/27 01:40:16 $ $Revision: 1.6 $
Number
270
Dependencies
OpenGL 1.1 is required.
The extension is written against the OpenGL 1.2.1 Specification.
Overview
This extension provides a simple mechanism to optimize texture data handling
by clients. GL implementations normally maintain a copy of texture image
data supplied clients when any of the various texturing commands, such as
TexImage2D, are invoked. This extension eliminates GL's internal copy of
the texture image data and allows a client to maintain this data locally for
textures when the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter is
TRUE at the time of texture specification. Local texture data storage is
especially useful in cases where clients maintain internal copies of
textures used in any case. This results in what could be considered an
extra copy of the texture image data. Assuming all operations are error
free, the use of client storage has no affect on the result of texturing
operations and will not affect rendering results. APPLE_client_storage
allows clients to optimize memory requirements and copy operations it also
requires adherence to specific rules in maintaining texture image data.
Clients using this extension are agreeing to preserve a texture's image data
for the life of the texture. The life of the texture is defined, in this
case, as the time from first issuing the TexImage3D, TexImage2D or
TexImage1D command, for the specific texture object with the
UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter set to TRUE, until the
DeleteTextures command or another TexImage command for that same object.
Only after DeleteTextures has completed, or new texture is specified, can
the local texture memory be released, as it will no longer be utilized by
OpenGL. Changing the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter
will have no additional effect once the texturing command has been issued
and specifically will not alleviate the client from maintaining the texture
data.
Client storage is implemented as a pixel storage parameter which affects
texture image storage at the time the texturing command is issued. As with
other pixel storage parameters this state may differ from the time the
texturing command in executed if the command is placed in a display list.
The PixelStore command is used to set the parameter
UNPACK_CLIENT_STORAGE_APPLE. Values can either be TRUE or FALSE, with TRUE
representing the use of client local storage and FALSE indicating the OpenGL
engine and not the client will be responsible for maintaining texture
storage for future texturing commands issued per the OpenGL specification.
The default state for the UNPACK_CLIENT_STORAGE_APPLE parameter is FALSE
Client storage is only available for texture objects and not the default
texture (of any target type). This means that a texture object has to
generated and bound to be used with client storage. Setting
UNPACK_CLIENT_STORAGE_APPLE to TRUE and texturing with the default texture
will result in normally texturing with GL maintaining a copy of the texture
image data.
Normally, client storage will be used in conjunction with normal texturing
techniques. An application would use GenTextures to generate texture
objects as needed. BindTexture to the texture object name of interest.
Enable client storage via the PixelStore command setting the
UNPACK_CLIENT_STORAGE_APPLE parameter to TRUE. Then use TexImage3D,
TexImage2D or TexImage1D to specify the texture image. If no further use of
client storage is desired, it is recommended to again use the PixelStore
command, in this case setting the UNPACK_CLIENT_STORAGE_APPLE parameter to
FALSE to disable client storage, since this pixel state is maintained unless
explicitly set by the PixelStore command.
If an application needs to modify the texture, using TexSubImage for
example, it should be noted that the pointer passed to TexSubImage1D,
TexSubImage2D or TexSubImage3D does not have to the same, or within the
original texture memory. It if is not, there is the likelihood of GL
copying the new data to the original texture memory owned by the client,
thus actually modifying this texture image data. This does not affect
requirement to maintain the original texture memory but also does not add
the requirement to maintain the sub image data, due to the copy.
Once a client has completed use of the texture stored in client memory, it
should issue a DeleteTextures command to delete the texture object or issue
a texture command, with the same target type, for the object, with either a
different data pointer, or UNPACK_CLIENT_STORAGE_APPLE set to false, in any
case, breaking the tie between GL and the texture buffer. An implicit Flush
command is issued in these cases, ensuring all access to the texture by
OpenGL is complete. Only at this point can the texture buffer be safely
released. Releasing the texture buffer prior has undefined results and will
very possibly display texel anomalies at run time. System level memory
management and paging schemes should not affect the use of client storage.
Consider in any case, that GL has an alias of the base pointer for this
block of texture memory which is maintained until GL is finished rendering
with the texture and it has been deleted or reassigned to another set of
texture data. As long as this alias exists, applications must not
de-allocate, move or purge this memory.
None
Accepted by the <pname> parameters of PixelStore:
UNPACK_CLIENT_STORAGE_APPLE 0x85B2
Additions to Chapter 3 of the 1.2.1 Specification (Rasterization)
- (3.6.1, p. 75) Add new PixelStore parameter:
Add to Table 3.1 (p. 76):
Parameter Name Type Initial Value Valid Range
-------------- ---- ------------- -----------
UNPACK_CLIENT_STORAGE_APPLE boolean FALSE TRUE/FALSE
- (3.8.1, p. 117) Last paragraph first sentence changed to:
"If the pixel storage parameter UNPACK_CLIENT_STORAGE_APPLE is false the
image indicated to the GL by the image pointer is decoded and copied into
the GLŐs internal memory."
- (3.8.1, p. 118) Add paragraphs before to last paragraph in section:
"If the pixel storage parameter UNPACK_CLIENT_STORAGE_APPLE is TRUE, GL
will not copy but instead will attempt to decode the texture image
data directly from client memory. GL will fall back to the default copy
and decode behavior if modifications to the texture image data are
required to decode the texels. This fall back may occur if ARB_imaging is
enabled, texture image data format or internal format indexed,
UNPACK_SWAP_BYTES is TRUE, or texturing from the default texture object.
Otherwise, GL will attempt to use the client local memory directly to
decode the texels.
Clients using the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter will
maintain a texture's image data for the life of the texture. The life of
the texture in this case is the time from issuing this texture command,
for the specific texture object, until the DeleteTextures command or
another texture command for this same texture object. Only after
DeleteTextures has completed, or new texture image data is specified, can
the client local memory be released. Releasing the texture buffer prior
has undefined results and will very possibly display texel anomalies at
run time. System level memory management and paging schemes should not
affect the use of client local storage. Consider, that GL has an alias of
the base pointer for this block of client memory which is maintained until
GL is finished rendering with the texture and it has been deleted or
reassigned to other texture image data. As long as this alias exists,
clients must not de-allocate, move or purge this memory. Otherwise,
texturing from with client local storage is unchanged from the default
copy and decode behavior."
- (3.8.2, p. 123) Add final paragraph in section:
"Note, if the existing target texture array has enabled client local
storage via the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter and if
client local storage is being used, TexSubImage and CopyTexImage may
directly modify the client memory being used as storage for a texture's
image data."
Additions to Chapter 6 of the 1.2.1 Specification (State and State Requests)
None
Additions to the GLX Specification
None
GLX Protocol
None
Errors
None (Texturing using client local storage behaves as texturing with client
local storage and no additional errors are generated)
New State
(table 6.17, p. 207)
Get Value Type Get Command Initial Value Description Sec. Attribute
--------- ---- ----------- ------------- ----------- ---- ---------
UNPACK_CLIENT_STORAGE_APPLE B GetBooleanv FALSE Value of 4.3 pixel-store
UNPACK_CLIENT_STORAGE_APPLE
New Implementation Dependent State
None
Implementation Support
List of OpenGL implementations supporting the GL_APPLE_client_storage extension
Original File
Original text file for the GL_APPLE_client_storage extension
Page generated on Sun Nov 20 18:38:59 2005