1Name 2 3 WGL_I3D_image_buffer 4 5Name Strings 6 7 WGL_I3D_image_buffer 8 9Contact 10 11 Dale Kirkland, Intense3D (kirkland 'at' intense3d.com) 12 13Status 14 15 Complete 16 17Version 18 19 Date: 04/18/2000 Revision 1.0 20 21Number 22 23 253 24 25Dependencies 26 27 The extension is written against the OpenGL 1.2.1 Specification 28 although it should work on any previous OpenGL specification. 29 30 The WGL_EXT_extensions_string extension is required. 31 32Overview 33 34 The image buffer extension provides an interface to allocate one 35 or more memory buffers to be used for GL image functions. These 36 functions include DrawPixels, ReadPixels, TexImage*D, and 37 TexSubImage*D. 38 39 The advantage of an image buffer over normal allocated memory is 40 as follows: 41 42 o The image buffer may be allocated on the graphics adapter. 43 44 o The image buffer may be locked once by the implementation thus 45 avoiding a call to the OS to lock the memory down each use. 46 47 o The data in the image buffer may be transferred to the adapter 48 using non-snooping accesses. 49 50 o Multiple events may be associated with the image buffer so that 51 the data can be transferred asynchronously. 52 53 Since the image buffer is created and maintained by a specific 54 graphics driver, a DC is required to create the image buffer. 55 However, the image buffer can be used with any RC created for the 56 graphics driver associated with the DC. 57 58IP Status 59 60 None 61 62Issues 63 64 None 65 66New Procedures and Functions 67 68 LPVOID wglCreateImageBufferI3D(HDC hDC, 69 DWORD dwSize, 70 UINT uFlags) 71 72 BOOL wglDestroyImageBufferI3D(HDC hDC, 73 LPVOID pAddress) 74 75 BOOL wglAssociateImageBufferEventsI3D(HDC hdc, 76 HANDLE *pEvent, 77 LPVOID *pAddress, 78 DWORD *pSize, 79 UINT count) 80 81 BOOL wglReleaseImageBufferEventsI3D(HDC hdc, 82 LPVOID *pAddress, 83 UINT count) 84 85New Tokens 86 87 Accepted by the <uFlags> parameter of wglCreateImageBufferI3D: 88 89 WGL_IMAGE_BUFFER_MIN_ACCESS_I3D 0x00000001 90 WGL_IMAGE_BUFFER_LOCK_I3D 0x00000002 91 92Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 93 94 None 95 96Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 97 98 None 99 100Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 101Operations and the Frame Buffer) 102 103 None 104 105Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 106 107 None 108 109Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and 110State Requests) 111 112 None 113 114Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance) 115 116 None 117 118Additions to the WGL Specification 119 120 An image buffer is memory allocated by the GL implementation that 121 can be used to store an image for more efficient transfers to the 122 graphics adapter. An image buffer is used with the following GL 123 image functions: DrawPixels, ReadPixels, TexImage*D, and 124 TexSubImage*D. 125 126 An image buffer is created by calling wglCreateImageBufferI3D: 127 128 LPVOID wglCreateImageBufferI3D(HDC hDC, 129 DWORD dwSize, 130 UINT uFlags) 131 132 <hDC> is a device context for the graphics adapter or a window 133 residing on the graphics adapter that supports the image buffer 134 extension. The image buffer can only be used for an RC created 135 on the graphics adapter associated with <hDC>. 136 137 <dwSize> is the requested byte size of the image buffer. The 138 minimum size is implementation-dependent, but at least <dwSize> 139 will be allocated for the image buffer. 140 141 <uFlags> specifies information about the intended usage of the 142 image buffer. 143 144 WGL_IMAGE_BUFFER_MIN_ACCESS_I3D 145 The image buffer is minimally accessed by the application; 146 rather, the buffer is loaded by a device (disk, graphics 147 adapter, etc.). The implementation may take advantage of 148 this and allocate memory that could be slower for the 149 host, but faster for devices. Also, the memory may be 150 allocated as uncached so that the data in the image buffer 151 does not have to be "snooped" during the transfer to or 152 from the graphics adapter. 153 154 WGL_IMAGE_BUFFER_LOCK_I3D 155 The image buffer memory is locked or allocated out of 156 memory that is not swapped. 157 158 If memory is available on the graphics adapter, the implementation 159 may choose to use it for the allocation of an image buffer. 160 However, the memory must behave like system memory in that it can 161 be read and written by system devices or the host. 162 163 If an image buffer is successfully created, a pointer is returned 164 to the image buffer memory. The boundary alignment for the image 165 buffer is at least the native alignment of the system (usually 166 32- or 64-bit alignment). 167 168 An image buffer can be destroyed by calling the function 169 wglDestroyImageBufferI3D. 170 171 BOOL wglDestroyImageBufferI3D(HDC hDC, 172 LPVOID pAddress) 173 174 <pAddress> is a pointer to an image buffer that was obtained from 175 a previous call to wglCreateImageBufferI3D. The implementation 176 will wait for any outstanding calls that use the image buffer to 177 complete before it is destroyed. If there is an event associated 178 with the image buffer, it must be freed by the caller after the 179 image buffer is destroyed. 180 181 If the call is successful, a value of TRUE is returned and the 182 resources associated with the image buffer are freed. 183 184 One or more events may be associated with the image buffer by 185 calling the function wglAssociateImageBufferEventsI3D. Each 186 event can be associated with a region of the image buffer to allow 187 asynchronous transfers between the image buffer and the graphics 188 adapter. 189 190 BOOL wglAssociateImageBufferEventsI3D(HDC hdc, 191 HANDLE *pEvent, 192 LPVOID *pAddress, 193 DWORD *pSize, 194 UINT count) 195 196 <pEvent> points to an array of events, each of which was created 197 with CreateEvent as a manual reset event with the initial state 198 set to TRUE (i.e. both the <bManualReset> and <bInitialState> 199 arguments must be set to a value of TRUE). All events must be 200 unique to only one portion of an image buffer (i.e., events 201 cannot be shared). 202 203 For each event in <pEvent>, a region in the image buffer is defined 204 by the corresponding <pAddress> and <pSize> entry. <count> 205 specifies the number of events (and associated regions). 206 207 All regions for a call to wglAssociateImageBufferEventsI3D must be 208 for the same image buffer. Additional events can be added at any 209 time. Regions must not overlap. The entire image buffer can be 210 defined as a single region. 211 212 Each region in an image buffer can be used as the image for 213 DrawPixels, ReadPixels, TexImage*D, and TexSubImage*D calls. 214 Once a call is made to a GL image function, the caller must wait 215 for the transfer to complete using WaitForSingleObject before the 216 image buffer can be modified (for DrawPixels, TexImage*D, or 217 TexSubImage*D) or read (for ReadPixels). 218 219 If an event is not specified for a region, the GL call using that 220 region will complete its transfer before it returns. 221 222 Events can be disassociated with their region by calling 223 wglReleaseImageBufferEventsI3D. 224 225 BOOL wglReleaseImageBufferEventsI3D(HDC hdc, 226 LPVOID *pAddress, 227 UINT count) 228 229 <pAddress> points to an array of regions previously associated 230 with events. <count> is the number of regions in the array. If an 231 event is associated with the specified region, it is released. All 232 regions specified by <pAddress> must be for the same image buffer. 233 234 When an image buffer is destroyed using wglDestroyImageBufferI3D, 235 all events for that image buffer are released. It is the 236 responsibility of the application to delete events that are no 237 longer associated with an image buffer. 238 239Dependencies on WGL_EXT_extensions_string 240 241 Because there is no way to extend wgl, these calls are defined in 242 the ICD and can be called by obtaining the address with 243 wglGetProcAddress. Because this extension is a WGL extension, it 244 is not included in the GL_EXTENSIONS string. Its existence can be 245 determined with the WGL_EXT_extensions_string extension. 246 247Errors 248 249 If the wglCreateImageBufferI3D function succeeds, a pointer to an 250 image buffer is returned. If the function fails, a value of NULL 251 is returned. To get extended error information, call GetLastError. 252 253 ERROR_DC_NOT_FOUND The <hDC> was not valid. 254 255 ERROR_NO_SYSTEM_RESOURCES There was insufficient resources to 256 support the request. 257 258 ERROR_INVALID_DATA <dwSize> is not a positive value. 259 260 If the wglDestroyImageBufferI3D function succeeds, a value of TRUE 261 is returned. If the function fails, a value of FALSE is returned. 262 To get extended error information, call GetLastError. 263 264 ERROR_DC_NOT_FOUND The <hDC> was not valid. 265 266 If the wglAssociateImageBufferEventsI3D or 267 wglReleaseImageBufferEventsI3D functions succeed, a value of TRUE 268 is returned. If the function fails, a value of FALSE is returned. 269 To get extended error information, call GetLastError. 270 271 ERROR_DC_NOT_FOUND The <hDC> was not valid. 272 273 ERROR_INVALID_DATA The regions specified by <pAddress> 274 are not valid for the specified image 275 buffer. 276 277New State 278 279 None 280 281New Implementation Dependent State 282 283 None 284 285Revision History 286 287 11/15/1999 0.1 First draft. 288 11/24/1999 0.2 Fixed various typos. 289 03/16/2000 0.3 Changed to add multiple events for a single image 290 buffer. 291 04/18/2000 1.0 Released driver to ISVs. 292