1Name 2 3 WGL_ARB_make_current_read 4 5Name Strings 6 7 WGL_ARB_make_current_read 8 9Contact 10 11 Dale Kirkland, NVIDIA (dkirkland 'at' nvidia.com) 12 13Notice 14 15 Copyright (c) 2000-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Complete. Approved by ARB on March 15, 2000. 31 32Version 33 34 Last Modified Date: 03/12/2002 35 Author Revision: 1.1 36 37 Based on: WGL_EXT_pbuffer specification 38 Date: 3/1/1999 Version: 1.5 39 40Number 41 42 ARB Extension #10 43 44Dependencies 45 46 WGL_ARB_extensions_string is required. 47 48Overview 49 50 The association of a separate "read" and "draw" DC with the current 51 context allows for preprocessing of image data in an "off screen" 52 DC which is then read into a visible DC for final display. 53 54New Procedures and Functions 55 56 BOOL wglMakeContextCurrentARB(HDC hDrawDC, 57 HDC hReadDC, 58 HGLRC hglrc); 59 60 HDC wglGetCurrentReadDCARB(VOID); 61 62New Tokens 63 64 New errors returned by GetLastError: 65 66 ERROR_INVALID_PIXEL_TYPE_ARB 0x2043 67 ERROR_INCOMPATIBLE_DEVICE_CONTEXTS_ARB 0x2054 68 69Additions to Chapter 2 of the 1.2 GL Specification (OpenGL Operation) 70 71 None 72 73Additions to Chapter 3 of the 1.2 GL Specification (Rasterization) 74 75 None 76 77Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations 78and the Frame buffer) 79 80 None 81 82Additions to Chapter 5 of the 1.2 Specification (Special Functions) 83 84 None 85 86Additions to Chapter 6 of the 1.2 Specification (State and State Requests) 87 88 None 89 90Additions to the GLX Specification 91 92 This specification is written for WGL. 93 94GLX Protocol 95 96 This specification is written for WGL. 97 98Additions to the WGL specification 99 100 The function wglMakeContextCurrentARB associates the context <hglrc> 101 with the device <hDrawDC> for draws and the device <hReadDC> for 102 reads. All subsequent OpenGL calls made by the calling thread are 103 drawn on the device identified by <hDrawDC> and read on the device 104 identified by <hReadDC>. 105 106 The <hDrawDC> and <hReadDC> parameters must refer to drawing 107 surfaces supported by OpenGL. These parameters need not be the 108 same <hdc> that was passed to wglCreateContext when <hglrc> was 109 created. <hDrawDC> must have the same pixel format and be created 110 on the same physical device as the <hdc> that was passed into 111 wglCreateContext. <hReadDC> must be created on the same device as 112 the <hdc> that was passed to wglCreateContext and it must support 113 the same pixel type as the pixel format of the <hdc> that was 114 passed to wglCreateContext. 115 116 If wglMakeContextCurrentARB is used to associate a different device 117 for reads than for draws, the "read" device will be used for the 118 following OpenGL operations: 119 120 1. Any pixel data that are sourced based on the value of READ_BUFFER. 121 Note, that accumulation operations use the value of READ_BUFFER, 122 but are not allowed when a different device context is used 123 for reads. In this case, the accumulation operation will 124 generate INVALID_OPERATION. 125 126 2. Any depth values that are retrieved by ReadPixels, CopyPixels, 127 or any OpenGL extension that sources depth images from the frame 128 buffer in the manner of ReadPixels and CopyPixels. 129 130 3. Any stencil values that are retrieved by ReadPixels, CopyPixels, 131 or any OpenGL extension that sources stencil images from the 132 framebuffer in the manner of ReadPixels and CopyPixels. 133 134 These frame buffer values are taken from the surface associated with 135 the device context specified by <hReadDC>. 136 137 No error will be generated if the value of READ_BUFFER at the time 138 the wglMakeContextCurrentARB call is made does not correspond to a 139 valid color buffer in <hReadDC>. Also, no error due to READ_BUFFER 140 mismatch will be generated by subsequent calls to any of the 141 operations enumerated above, but the pixels values used will be 142 undefined until READ_BUFFER is set to a color buffer that is valid 143 in the <hReadDC>. Operations that query the value of READ_BUFFER 144 (i.e., Get, PushAttrib) use the value set last in the context, 145 independent of whether it is a valid buffer in <hReadDC>. 146 147 Error conditions set by ReadBuffer and by the operations enumerated 148 above are with respect to color and ancillary buffers available in 149 <hReadDC> (i.e., ReadBuffer(BACK_BUFFER) will generate an error 150 when <hReadDC> is single buffered, and so will an operation that 151 tries to source stencil images when <hReadDC> does not have a 152 stencil buffer). When the read buffer is set implicitly via 153 PopAttrib to a state not supported by the pixel format, an error 154 may be generated. 155 156 If wglMakeContextCurrentARB succeeds, the return value is TRUE. 157 If the function fails, the return value is FALSE. To get extended 158 error information, call GetLastError. Possible errors are as follows: 159 160 ERROR_INVALID_PIXEL_FORMAT The pixel format associated with 161 <hDrawDC> does not match the pixel 162 format associated with the render 163 context. 164 165 ERROR_INVALID_PIXEL_TYPE_ARB The pixel type for <hReadDC> is 166 different than the pixel type 167 associated with the <hdc> that was 168 passed to wglCreateContext. 169 170 ERROR_INCOMPATIBLE_DEVICE_CONTEXTS_ARB 171 The device contexts specified by 172 <hReadDC> and <hDrawDC> are not 173 compatible. This can occur if the 174 device contexts are managed by 175 different drivers or possibly on 176 different graphics adapters. 177 178 ERROR_DC_NOT_FOUND <hReadDC> or <hDrawDC> is not a valid 179 device context. 180 181 ERROR_NO_SYSTEM_RESOURCES The device contexts specified by 182 <hReadDC> and <hDrawDC> cannot exist 183 in the framebuffer simultaneously. 184 185 wglGetCurrentReadDC returns a handle to the "read" device context that 186 is associated with the current OpenGL rendering context of the calling 187 thread. If the calling thread does not have a current context, the 188 return value is NULL. 189 190Dependencies on WGL_ARB_extensions_string 191 192 Because there is no way to extend wgl, these calls are defined in 193 the ICD and can be called by obtaining the address with 194 wglGetProcAddress. Because this extension is a WGL extension, it 195 is not included in the GL_EXTENSIONS string. Its existence can be 196 determined with the WGL_ARB_extensions_string extension. 197 198New State 199 200 None 201 202New Implementation Dependent State 203 204 None 205 206Conformance Testing 207 208 1. Create two non-overlapping windows (windows 1 and 2). 209 2. Create three contexts (context A, B, and C). 210 3. Set context A to draw to window 1 and read from window 1. 211 4. Set context B to draw to window 2 and read from window 1. 212 5. Set context C to draw to window 2 and read from window 2. 213 6. For a conformance test (TBD), 214 a. Draw using context A. 215 b. Blit from window to window using context B. 216 c. Test conformance using context C. 217 7. If pixel buffers are supported, repeat using a pixel buffer. 218 219Revision History 220 221 12/16/1999 0.1 222 - First ARB draft based on the EXT specification. 223 224 03/15/2000 0.2 225 - Removed the changes to Chapter 4. 226 - Added a discussion that accumulation operations may 227 generate INVALID_OPERATION. 228 - PopAttrib may (not will) generate an error. 229 - Added an error if the read and draw DCs are not managed 230 on the same driver. 231 232 03/22/2000 1.0 233 - Changed rendering context to device context. 234 - Added the new error conditions values. 235 - Approved by ARB: 10-0-0. 236 237 03/12/2002 1.1 238 - Updated contact information. 239