1Name
2
3    APPLE_client_storage
4	
5Name Strings
6
7    GL_APPLE_client_storage
8
9Contact
10
11    Geoff Stahl, Apple (gstahl 'at' apple.com)
12
13Status
14
15    Complete
16
17Version
18
19    $Date: 2002/08/27 01:40:16 $ $Revision: 1.6 $
20
21Number
22
23    270
24	
25Dependencies
26
27    OpenGL 1.1 is required.
28    The extension is written against the OpenGL 1.2.1 Specification.
29	
30Overview
31
32	This extension provides a simple mechanism to optimize texture data handling
33	by clients.  GL implementations normally maintain a copy of texture image
34	data supplied clients when any of the various texturing commands, such as
35	TexImage2D, are invoked.  This extension eliminates GL's internal copy of
36	the texture image data and allows a client to maintain this data locally for
37	textures when the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter is
38	TRUE at the time of texture specification.  Local texture data storage is
39	especially useful in cases where clients maintain internal copies of
40	textures used in any case.  This results in what could be considered an
41	extra copy of the texture image data.  Assuming all operations are error
42	free, the use of client storage has no affect on the result of texturing
43	operations and will not affect rendering results. APPLE_client_storage
44	allows clients to optimize memory requirements and copy operations it also
45	requires adherence to specific rules in maintaining texture image data.
46
47	Clients using this extension are agreeing to preserve a texture's image data
48	for the life of the texture.  The life of the texture is defined, in this
49	case, as the time from first issuing the TexImage3D, TexImage2D or
50	TexImage1D command, for the specific texture object with the
51	UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter set to TRUE, until the
52	DeleteTextures command or another TexImage command for that same object. 
53	Only after DeleteTextures has completed, or new texture is specified, can
54	the local texture memory be released, as it will no longer be utilized by
55	OpenGL.  Changing the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter
56	will have no additional effect once the texturing command has been issued
57	and specifically will not alleviate the client from maintaining the texture
58	data.
59
60	Client storage is implemented as a pixel storage parameter which affects
61	texture image storage at the time the texturing command is issued.  As with
62	other pixel storage parameters this state may differ from the time the
63	texturing command in executed if the command is placed in a display list. 
64	The PixelStore command is used to set the parameter
65	UNPACK_CLIENT_STORAGE_APPLE.  Values can either be TRUE or FALSE, with TRUE
66	representing the use of client local storage and FALSE indicating the OpenGL
67	engine and not the client will be responsible for maintaining texture
68	storage for future texturing commands issued per the OpenGL specification.
69	The default state for the UNPACK_CLIENT_STORAGE_APPLE parameter is FALSE
70
71	Client storage is only available for texture objects and not the default
72	texture (of any target type).  This means that a texture object has to
73	generated and bound to be used with client storage.  Setting
74	UNPACK_CLIENT_STORAGE_APPLE to TRUE and texturing with the default texture
75	will result in normally texturing with GL maintaining a copy of the texture
76	image data.
77
78	Normally, client storage will be used in conjunction with normal texturing
79	techniques.  An application would use GenTextures to generate texture
80	objects as needed.  BindTexture to the texture object name of interest. 
81	Enable client storage via the PixelStore command setting the
82	UNPACK_CLIENT_STORAGE_APPLE parameter to TRUE. Then use TexImage3D,
83	TexImage2D or TexImage1D to specify the texture image.  If no further use of
84	client storage is desired, it is recommended to again use the PixelStore
85	command, in this case setting the UNPACK_CLIENT_STORAGE_APPLE parameter to
86	FALSE to disable client storage, since this pixel state is maintained unless
87	explicitly set by the PixelStore command.
88
89	If an application needs to modify the texture, using TexSubImage for
90	example, it should be noted that the pointer passed to TexSubImage1D,
91	TexSubImage2D or TexSubImage3D does not have to the same, or within the
92	original texture memory.  It if is not, there is the likelihood of GL
93	copying the new data to the original texture memory owned by the client,
94	thus actually modifying this texture image data.  This does not affect
95	requirement to maintain the original texture memory but also does not add
96	the requirement to maintain the sub image data, due to the copy.
97
98	Once a client has completed use of the texture stored in client memory, it
99	should issue a DeleteTextures command to delete the texture object or issue
100	a texture command, with the same target type, for the object, with either a
101	different data pointer, or UNPACK_CLIENT_STORAGE_APPLE set to false, in any
102	case, breaking the tie between GL and the texture buffer.  An implicit Flush
103	command is issued in these cases, ensuring all access to the texture by
104	OpenGL is complete.  Only at this point can the texture buffer be safely
105	released.  Releasing the texture buffer prior has undefined results and will
106	very possibly display texel anomalies at run time.  System level memory
107	management and paging schemes should not affect the use of client storage. 
108	Consider in any case, that GL has an alias of the base pointer for this
109	block of texture memory which is maintained until GL is finished rendering
110	with the texture and it has been deleted or reassigned to another set of
111	texture data.  As long as this alias exists, applications must not
112	de-allocate, move or purge this memory.
113
114New Procedures and Functions
115
116	None
117	
118New Tokens
119
120	Accepted by the <pname> parameters of PixelStore:
121
122	UNPACK_CLIENT_STORAGE_APPLE    0x85B2
123
124Additions to Chapter 3 of the 1.2.1 Specification (Rasterization)
125
126	
127    - (3.6.1, p. 75) Add new PixelStore parameter:
128	
129	Add to Table 3.1 (p. 76):
130
131      Parameter Name               Type     Initial Value    Valid Range
132      --------------               ----     -------------    -----------
133      UNPACK_CLIENT_STORAGE_APPLE  boolean  FALSE            TRUE/FALSE
134    
135    - (3.8.1, p. 117) Last paragraph first sentence changed to:
136
137	  "If the pixel storage parameter UNPACK_CLIENT_STORAGE_APPLE is false the
138	  image indicated to the GL by the image pointer is decoded and copied into
139	  the GL's internal memory."
140    
141    - (3.8.1, p. 118) Add paragraphs before to last paragraph in section:
142
143	  "If the pixel storage parameter UNPACK_CLIENT_STORAGE_APPLE is TRUE, GL
144	  will not copy but instead will attempt to decode the texture image
145	  data directly from client memory.  GL will fall back to the default copy
146	  and decode behavior if modifications to the texture image data are
147	  required to decode the texels.  This fall back may occur if ARB_imaging is
148	  enabled, texture image data format or internal format indexed,
149	  UNPACK_SWAP_BYTES is TRUE, or texturing from the default texture object. 
150	  Otherwise, GL will attempt to use the client local memory directly to
151	  decode the texels.
152
153	  Clients using the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter will
154	  maintain a texture's image data for the life of the texture.  The life of
155	  the texture in this case is the time from issuing this texture command,
156	  for the specific texture object, until the DeleteTextures command or
157	  another texture command for this same texture object. Only after
158	  DeleteTextures has completed, or new texture image data is specified, can
159	  the client local memory be released.  Releasing the texture buffer prior
160	  has undefined results and will very possibly display texel anomalies at
161	  run time.  System level memory management and paging schemes should not
162	  affect the use of client local storage. Consider, that GL has an alias of
163	  the base pointer for this block of client memory which is maintained until
164	  GL is finished rendering with the texture and it has been deleted or
165	  reassigned to other texture image data.  As long as this alias exists,
166	  clients must not de-allocate, move or purge this memory.  Otherwise,
167	  texturing from with client local storage is unchanged from the default
168	  copy and decode behavior."
169
170    - (3.8.2, p. 123) Add final paragraph in section:
171
172	  "Note, if the existing target texture array has enabled client local
173	  storage via the UNPACK_CLIENT_STORAGE_APPLE pixel storage parameter and if
174	  client local storage is being used, TexSubImage and CopyTexImage may
175	  directly modify the client memory being used as storage for a texture's
176	  image data."
177	  
178Additions to Chapter 6 of the 1.2.1 Specification (State and State Requests)
179
180	None
181	
182Additions to the GLX Specification
183
184	None
185	
186GLX Protocol
187
188	None
189	
190Errors
191
192	None (Texturing using client local storage behaves as texturing with client
193	local storage and no additional errors are generated)
194
195New State
196	(table 6.17, p. 207)
197	Get Value                   Type  Get Command Initial Value Description                 Sec. Attribute
198	---------                   ----  ----------- ------------- -----------                 ---- ---------
199	UNPACK_CLIENT_STORAGE_APPLE B     GetBooleanv FALSE         Value of                    4.3  pixel-store
200                                                                UNPACK_CLIENT_STORAGE_APPLE
201
202New Implementation Dependent State
203
204	None
205