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 Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL Working Group. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php 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 with the device for draws and the device for reads. All subsequent OpenGL calls made by the calling thread are drawn on the device identified by and read on the device identified by . The and parameters must refer to drawing surfaces supported by OpenGL. These parameters need not be the same that was passed to wglCreateContext when was created. must have the same pixel format and be created on the same physical device as the that was passed into wglCreateContext. must be created on the same device as the that was passed to wglCreateContext and it must support the same pixel type as the pixel format of the 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 . 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 . 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 . 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 . Error conditions set by ReadBuffer and by the operations enumerated above are with respect to color and ancillary buffers available in (i.e., ReadBuffer(BACK_BUFFER) will generate an error when is single buffered, and so will an operation that tries to source stencil images when 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 does not match the pixel format associated with the render context. ERROR_INVALID_PIXEL_TYPE_ARB The pixel type for is different than the pixel type associated with the that was passed to wglCreateContext. ERROR_INCOMPATIBLE_DEVICE_CONTEXTS_ARB The device contexts specified by and 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 or is not a valid device context. ERROR_NO_SYSTEM_RESOURCES The device contexts specified by and 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.