| Name |
| |
| WGL_ARB_make_current_read |
| |
| Name Strings |
| |
| WGL_ARB_make_current_read |
| |
| Contact |
| |
| Dale Kirkland, NVIDIA (dkirkland 'at' nvidia.com) |
| |
| Notice |
| |
| Copyright (c) 2000-2013 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Status |
| |
| Complete. Approved by ARB on March 15, 2000. |
| |
| Version |
| |
| Last Modified Date: 03/12/2002 |
| Author Revision: 1.1 |
| |
| Based on: WGL_EXT_pbuffer specification |
| Date: 3/1/1999 Version: 1.5 |
| |
| Number |
| |
| ARB Extension #10 |
| |
| Dependencies |
| |
| WGL_ARB_extensions_string is required. |
| |
| Overview |
| |
| The association of a separate "read" and "draw" DC with the current |
| context allows for preprocessing of image data in an "off screen" |
| DC which is then read into a visible DC for final display. |
| |
| New Procedures and Functions |
| |
| BOOL wglMakeContextCurrentARB(HDC hDrawDC, |
| HDC hReadDC, |
| HGLRC hglrc); |
| |
| HDC wglGetCurrentReadDCARB(VOID); |
| |
| New Tokens |
| |
| New errors returned by GetLastError: |
| |
| ERROR_INVALID_PIXEL_TYPE_ARB 0x2043 |
| ERROR_INCOMPATIBLE_DEVICE_CONTEXTS_ARB 0x2054 |
| |
| Additions to Chapter 2 of the 1.2 GL Specification (OpenGL Operation) |
| |
| None |
| |
| Additions to Chapter 3 of the 1.2 GL Specification (Rasterization) |
| |
| None |
| |
| Additions to Chapter 4 of the 1.2 Specification (Per-Fragment Operations |
| and the Frame buffer) |
| |
| None |
| |
| Additions to Chapter 5 of the 1.2 Specification (Special Functions) |
| |
| None |
| |
| Additions to Chapter 6 of the 1.2 Specification (State and State Requests) |
| |
| None |
| |
| Additions to the GLX Specification |
| |
| This specification is written for WGL. |
| |
| GLX Protocol |
| |
| This specification is written for WGL. |
| |
| Additions to the WGL specification |
| |
| The function wglMakeContextCurrentARB associates the context <hglrc> |
| with the device <hDrawDC> for draws and the device <hReadDC> for |
| reads. All subsequent OpenGL calls made by the calling thread are |
| drawn on the device identified by <hDrawDC> and read on the device |
| identified by <hReadDC>. |
| |
| The <hDrawDC> and <hReadDC> parameters must refer to drawing |
| surfaces supported by OpenGL. These parameters need not be the |
| same <hdc> that was passed to wglCreateContext when <hglrc> was |
| created. <hDrawDC> must have the same pixel format and be created |
| on the same physical device as the <hdc> that was passed into |
| wglCreateContext. <hReadDC> must be created on the same device as |
| the <hdc> that was passed to wglCreateContext and it must support |
| the same pixel type as the pixel format of the <hdc> that was |
| passed to wglCreateContext. |
| |
| If wglMakeContextCurrentARB is used to associate a different device |
| for reads than for draws, the "read" device will be used for the |
| following OpenGL operations: |
| |
| 1. Any pixel data that are sourced based on the value of READ_BUFFER. |
| Note, that accumulation operations use the value of READ_BUFFER, |
| but are not allowed when a different device context is used |
| for reads. In this case, the accumulation operation will |
| generate INVALID_OPERATION. |
| |
| 2. Any depth values that are retrieved by ReadPixels, CopyPixels, |
| or any OpenGL extension that sources depth images from the frame |
| buffer in the manner of ReadPixels and CopyPixels. |
| |
| 3. Any stencil values that are retrieved by ReadPixels, CopyPixels, |
| or any OpenGL extension that sources stencil images from the |
| framebuffer in the manner of ReadPixels and CopyPixels. |
| |
| These frame buffer values are taken from the surface associated with |
| the device context specified by <hReadDC>. |
| |
| No error will be generated if the value of READ_BUFFER at the time |
| the wglMakeContextCurrentARB call is made does not correspond to a |
| valid color buffer in <hReadDC>. Also, no error due to READ_BUFFER |
| mismatch will be generated by subsequent calls to any of the |
| operations enumerated above, but the pixels values used will be |
| undefined until READ_BUFFER is set to a color buffer that is valid |
| in the <hReadDC>. Operations that query the value of READ_BUFFER |
| (i.e., Get, PushAttrib) use the value set last in the context, |
| independent of whether it is a valid buffer in <hReadDC>. |
| |
| Error conditions set by ReadBuffer and by the operations enumerated |
| above are with respect to color and ancillary buffers available in |
| <hReadDC> (i.e., ReadBuffer(BACK_BUFFER) will generate an error |
| when <hReadDC> is single buffered, and so will an operation that |
| tries to source stencil images when <hReadDC> does not have a |
| stencil buffer). When the read buffer is set implicitly via |
| PopAttrib to a state not supported by the pixel format, an error |
| may be generated. |
| |
| If wglMakeContextCurrentARB succeeds, the return value is TRUE. |
| If the function fails, the return value is FALSE. To get extended |
| error information, call GetLastError. Possible errors are as follows: |
| |
| ERROR_INVALID_PIXEL_FORMAT The pixel format associated with |
| <hDrawDC> does not match the pixel |
| format associated with the render |
| context. |
| |
| ERROR_INVALID_PIXEL_TYPE_ARB The pixel type for <hReadDC> is |
| different than the pixel type |
| associated with the <hdc> that was |
| passed to wglCreateContext. |
| |
| ERROR_INCOMPATIBLE_DEVICE_CONTEXTS_ARB |
| The device contexts specified by |
| <hReadDC> and <hDrawDC> are not |
| compatible. This can occur if the |
| device contexts are managed by |
| different drivers or possibly on |
| different graphics adapters. |
| |
| ERROR_DC_NOT_FOUND <hReadDC> or <hDrawDC> is not a valid |
| device context. |
| |
| ERROR_NO_SYSTEM_RESOURCES The device contexts specified by |
| <hReadDC> and <hDrawDC> cannot exist |
| in the framebuffer simultaneously. |
| |
| wglGetCurrentReadDC returns a handle to the "read" device context that |
| is associated with the current OpenGL rendering context of the calling |
| thread. If the calling thread does not have a current context, the |
| return value is NULL. |
| |
| Dependencies on WGL_ARB_extensions_string |
| |
| Because there is no way to extend wgl, these calls are defined in |
| the ICD and can be called by obtaining the address with |
| wglGetProcAddress. Because this extension is a WGL extension, it |
| is not included in the GL_EXTENSIONS string. Its existence can be |
| determined with the WGL_ARB_extensions_string extension. |
| |
| New State |
| |
| None |
| |
| New Implementation Dependent State |
| |
| None |
| |
| Conformance Testing |
| |
| 1. Create two non-overlapping windows (windows 1 and 2). |
| 2. Create three contexts (context A, B, and C). |
| 3. Set context A to draw to window 1 and read from window 1. |
| 4. Set context B to draw to window 2 and read from window 1. |
| 5. Set context C to draw to window 2 and read from window 2. |
| 6. For a conformance test (TBD), |
| a. Draw using context A. |
| b. Blit from window to window using context B. |
| c. Test conformance using context C. |
| 7. If pixel buffers are supported, repeat using a pixel buffer. |
| |
| Revision History |
| |
| 12/16/1999 0.1 |
| - First ARB draft based on the EXT specification. |
| |
| 03/15/2000 0.2 |
| - Removed the changes to Chapter 4. |
| - Added a discussion that accumulation operations may |
| generate INVALID_OPERATION. |
| - PopAttrib may (not will) generate an error. |
| - Added an error if the read and draw DCs are not managed |
| on the same driver. |
| |
| 03/22/2000 1.0 |
| - Changed rendering context to device context. |
| - Added the new error conditions values. |
| - Approved by ARB: 10-0-0. |
| |
| 03/12/2002 1.1 |
| - Updated contact information. |