xref: /third_party/openGLES/extensions/EXT/WGL_EXT_make_current_read.txt

Name

    EXT_make_current_read

Name Strings

    WGL_EXT_make_current_read

Version

    Date: 3/1/1999   Version: 1.5

Number

    169

Dependencies

    WGL_EXT_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 wglMakeContextCurrentEXT(HDC hDrawDC,
                                  HDC hReadDC,
                                  HGLRC hglrc);

    HDC wglGetCurrentReadDCEXT(VOID);

New Tokens

    Returned by GetLastError (when wglMakeContextCurrentEXT fails):

	ERROR_INVALID_PIXEL_TYPE_EXT		0x2043

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)

    [The following restriction is added to the end of the introductory
    paragraph of section 4.2.4]

    Accumulation operations are only allowed when the device context used
    for reading is identical to the device context used for drawing.

    [The list of error conditions at the end of section 4.2.4]
    If there is no accumulation buffer, or the GL is in color index mode,
    or if the read device context and the draw device context are not
    identical, Accum generates the error INVALID_OPERATION.

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 WGL specification

    The function wglMakeContextCurrentEXT 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 device as the <hdc> that was passed into wlgCreateContext.
    <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 wglMakeContextCurrentEXT 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 rendering context is used
        for reads.

    2.  Any depth values that are retrieved by glReadPixels, glCopyPixels,
        or any OpenGL extension that sources depth images from the frame
        buffer in the manner of glReadPixels and glCopyPixels.

    3.  Any stencil values that are retrieved by glReadPixels, glCopyPixels,
        or any OpenGL extension that sources stencil images from the frame
        buffer in the manner of glReadPixels and glCopyPixels.

    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
    wglMakeContextCurrentEXT 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., glGet, glPushAttrib) use the
    value set last in the context, independent of whether it is a valid
    buffer in <hReadDC>.

    Error conditions set by glReadBuffer (even when called implicitly via
    glPopAttrib) and by the operations enumerated above are with respect
    to color and ancillary buffers available in <hReadDC> (i.e.,
    glReadBuffer(GL_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).

    If wglMakeContextCurrentEXT 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_EXT   The pixel type for <hReadDC> is
                                     different than the pixel type
                                     associated with the <hdc> that was
                                     passed to wglCreateContext.
      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.

    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 is not a GL extension, it is not included in the
    GL_EXTENSIONS string.

New State

    None

New Implementation Dependent State

   None