xref: /third_party/openGLES/extensions/ARB/WGL_ARB_make_current_read.txt

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 <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.