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

Name 

    ARB_render_texture 

Name Strings 

    WGL_ARB_render_texture 

Contact 

    Bimal Poddar, Intel, bimal.poddar@intel.com
    Paula Womack, Nvidia, PWomack@nvidia.com

Notice

    Copyright (c) 2001-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 June 13, 2001

Version 

    Last Modified Date: July 16, 2001

Number 

    ARB Extension #20 

Dependencies 

    OpenGL 1.1 is required. 
    WGL_ARB_extension_string is required. 
    WGL_ARB_pixel_format is required. 
    WGL_ARB_pbuffer is required. 
    WGL_ARB_make_current_read affects the definition of this extension. 
    GL_ARB_texture_cube_map affects the definition of this extension 
    The extension is written against the OpenGL 1.2.1 Specification. 

Overview 

    This extension allows a color buffer to be used for both rendering and
    texturing. When a color buffer is bound to a texture target it cannot 
    be rendered to. Once it has been released from the texture it can be 
    rendered to once again. 

    This extension may provide a performance boost and reduce memory 
    requirements on architectures that support rendering to the same 
    memory where textures reside and in the same memory format and layout
    required by texturing. The functionality is similar to CopyTexImage1D
    and CopyTexImage2D. However, some changes were made to make it easier 
    to avoid copying data: 

    -   Only color buffers of a pbuffer can be bound as a texture. It is 
        not possible to use the color buffer of a window as a texture. 

    -   The texture internal format is determined when the color buffer 
        is associated with the texture, guaranteeing that the color 
        buffer format is equivalent to the texture internal format. 
        
    -   When a color buffer of a pbuffer is being used as a texture, 
        the pbuffer can not be used for rendering; this makes it 
        easier for implementations to avoid a copy of the image 
        since the semantics of the pointer swap are clear. 

    -   The application must release the color buffer from the texture 
        before it can render to the pbuffer again. When the color buffer 
        is bound as a texture, draw and read operations on the pbuffer 
        are undefined. 

    -   A mipmap attribute can be set, in which case memory will be 
        allocated up front for mipmaps. The application can render 
        the mipmap images or, if SGIS_generate_mipmap is supported, 
        they can be automatically generated when the color buffer is 
        bound as a texture. 

    -   A texture target is associated with the pbuffer, so that cubemap 
        images can be rendered into a single color buffer. 

    Note that this extension may be used in conjunction with other 
    extensions to associate video images/buffers to pbuffers.  Once the 
    video image is associated with a pbuffer it can be used as a texture.
    Also, if SGIX_generate_mipmap is supported, it is possible to 
    create a complete set of mipmap images from a single color buffer. 

IP Status 

    There are no known IP issues. 

Issues 

 1. Should we support 3D textures? What about 1D textures? 

    3D textures - No. This adds a lot of implementation burden without 
    having a good usage model.

    1D textures - Yes. Just a special case of 2D texture.

 2. Should we allow a portion of the color buffer to be used as a texture? 
    No, if a different size texture is needed the application can just 
    create another pbuffer. 

 3. Do we need the MIPMAP_TEXTURE attribute? 

    Yes this is good to have since some architectures may require all or 
    some of the mipmaps to be stored together in memory. 

 4. Should we require power of 2 textures? 

    Yes, we will allow an implementation to fail if the texture size is 
    not a power of 2. This restriction can be relaxed later by the
    exension that allows non-power of 2 texture.

 5. Should the render texture attributes be per color buffer or per drawable? 

    There really isn't a mechanism for associating attributes with the color
    buffer. Also, allowing different render texture attributes for each 
    color buffer makes the extension more difficult to implement without 
    providing a very useful tool for applications. 

 6. What should happen if the color buffer is used for rendering before it 
    is released from the texture? 

    There are three reasonable options: generate an error, create another 
    buffer or have the rendering results be undefined.  Since this is an 
    error condition, and not a useful feature, we should pick the option 
    that is easiest to implement.  For now, we choose to have the rendering 
    results be undefined--the rendering commands will be processed and the 
    context will be updated but the pbuffer may or may  not be updated. 
    Note that the pbuffer that contains the color buffer can be bound to a 
    different context, so the invalid state must be stored with the pbuffer,
    not the context.. (Also the texture object that contains the 
    color buffer's image may be released from the current context). 

 7. Should the new pbuffer attributes be available through GL queries? 

    No, like other pbuffer attributes you need to query them through the 
    window system extension. This extension does not make any changes to 
    OpenGL. 

 8. Should we allow a subset of mipmaps to be defined? 

    No. 

 9. What happens when a pbuffer is bound as a texture and then a mode 
    change occurs and the pbuffer is lost? 

    The texture is not lost in this case. OpenGL doesn't have the notion 
    of volatile textures and this extension should not introduce them. 
    (It may be an interesting additional extension). When a color buffer 
    is bound to a texture, it must be saved and restored by the driver, 
    whenever texture memory is lost (even on a windows mode change). 

10. Should there be any restrictions on the texture operations that 
    can be performed on a color buffer? 

    Yes. We allow TexSubImage and CopyTexSubImage calls but disallow 
    TexImage and CopyTexImage calls. When a TexImage or CopyTexImage call 
    is made then the color buffer is released back to the pbuffer and 
    new memory is allocated for the texture. No mixing and matching of 
    images is allowed. In other words, it is not possible to render a 
    non-mipmapped image to a pbuffer, bind it to a texture and then 
    call TexImage2D to create the other mipmap levels. Modifying any 
    mipmap level via TexImage or CopyTexImage will cause the color 
    buffer to be released back to the pbuffer, even if that level 
    was not defined by the color buffer. 

    Also, if DeleteTextures is called on the texture target, then the 
    color buffer that is bound to the texture target is released back 
    to the pbuffer.

    The implicit release of the color buffer is intended to work just
    like an explicit release - i.e. the color buffer is available for
    rendering without the app having to call ReleaseTexImage.
    
11. When the color buffer is released from the texture (back to the pbuffer)
    should the contents be preserved? 

    No, this may prove difficult to implement on some architectures. 

12. Should releasing the color buffer from the texture (back to the pbuffer)
    affect the scissor or viewport? 

    No, since releasing the color buffer, does not change its size, it 
    should not affect the scissor or viewport. The application is also 
    responsible for updating the viewport and scissor when changing which 
    mipmap level it is rendering to (this is similar to window resize, 
    where the application is responsible for updating the scissor and 
    viewport).

13. How should swap buffers work when a color buffer is bound as a texture? 

    Since a color buffer (not a pbuffer) is bound to a texture, swap buffers
    should be a no-op. Otherwise the name of the bound buffer (FRONT, BACK) 
    will change while it is bound. Note that swap buffers works just as
    for a pbuffer when the color buffer is not bound as a texture.

14. What happens when the application binds one color buffer of a pbuffer 
    to a texture and then tries to render to another color buffer of the 
    pbuffer? 

    If any of the pbuffer's color buffers are bound to a texture, then 
    rendering results are undefined for all color buffers of the pbuffer. 

15. Should it be an error to bind a color buffer of a pbuffer to a 
    texture, if that pbuffer is current to another thread? 

    No. It is not an error to make a drawable current to two threads right 
    now. Read and draw operations produce indeterminate results when the 
    pbuffer is bound to a texture. 

16. Should we allow color buffers of all drawables (pbuffers and windows)
    to be bound to textures? 

    For now we just allow pbuffers. This is simpler since they are not 
    shared with the window system and the color buffers are not part of the 
    visible framebuffer. Also, windows can be resized at any time and 
    handling this resize would unnecessarily complicate this extension. 

17. Should we allow depth buffers to be bound as textures? 

    This extension does not provide for this but it would be an interesting 
    additional extension. When a color buffer is bound to a texture, only 
    the color buffer is moved--ancillary buffers continue to be bound to 
    the pbuffer. 

    This extension is written such that adding depth textures should
    be very easy.

18. What happens when a color buffer is bound to a shared texture object? 

    Since the color buffer is associated with the texture object itself, 
    it should be shared. 

19. Should we specify how this extension interacts with SGIS_generate_mipmap? 

    No, since this is a potential ARB extension and SGIS_generate_mipmap 
    is not. If SGIS_generate_mipmap is supported along with this extension,
    then if wglBindTexImageARB is called and both GENERATE_MIPMAP_SGIS and 
    WGL_MIPMAP_TEXTURE_ARB are TRUE, then a set of mipmaps should be 
    generated. This behaviour needs to be documented in the 
    SGIS_generate_mipmap (or equivalent) extension. 

20. Should we support borders on render textures? 

    No. Although borders are part of 1.2.1, they are often not supported 
    and better techniques (such as virtual textures) are starting to 
    become available for paging in large textures. 

21. Should wglBindTexImageARB take an attribute indicating whether 
    mipmaps are defined or should this be implied from the 
    WGL_MIPMAP_TEXTURE_ARB attribute of the pbuffer? 

    This should be implied from the WGL_MIPMAP_TEXTURE_ARB attribute 
    since GL allows controls for the applications to use only level zero 
    image even if the pbuffer has been defined large enough to
    store mipmaps.

22. This extension introduces pbuffer attributes that can be modified. 
    (Previously all pbuffer attributes were static and could not be 
    changed.) Should we allow the non-static attributes to be set when the 
    pbuffer is created or should we require the application to call 
    wglSetPbufferAttribARB? 

    We require the application to call wglSetPbufferAttribARB to set 
    non-static Pbuffer attributes since this seems to be more consistent 
    with OpenGL specification.

23. Do we need WGL_TEXTURE_FORMAT_ARB or is WGL_ALPHA_BITS_ARB enough
    to distinguish between selecting RGB vs. RGBA textures? Additionally,
    how is this parameter defined for non texture buffers.

    Resolved: In order to accommodate RGBA visuals to support RGB textures
    (i.e. ignore alpha) and to allow the specification to be extensible
    for depth textures, WGL_TEXTURE_FORMAT_ARB is required in this
    specification. This parameter is defined as WGL_NO_TEXTURE_ARB for
    non texture buffers.

24. Should luminance and Intensity texture formats be allowed?

    No. WGL doesn't support single-channel framebuffer formats. Allowing
    these formats would require a copy to reformat a RGB/RGBA framebuffer
    to a Luminance or Intensity format. If luminance framebuffer gets
    added to WGL, then this feature can be added at that time.

Implementation Notes

 1. In order to prevent releases of a pbuffer from the texture object
    and to deal with implicit release followed by an explicit release,
    the GL implementation can keep a reference to any texture pbuffer
    in the texture object. When the pbuffer is released, this handle
    is set to NULL. Subsequent requests for releasing the texture
    pbuffer are ignored.

 2. The implicit release of the color buffers has been specifed to 
    work just like the explicit release so that the implementation
    can delete a texture object (one of the implicit free cases) without 
    having to track whether the texture was associated with any color buffers.

Intended Usage 

    To define a cube map texture, single threaded case 

    1)  Create the rendering window. Call wglChoosePixelFormatARB and 
        find a suitable pixel format for rendering the image. Set the pixel 
        format for the rendering window to this pixel format. 

    2)  Create the pbuffer. Call wglChoosePixelFormatARB and find a 
        suitable pixel format for rendering the texture.  
        WGL_DRAW_TO_PBUFFER and WGL_BIND_TO_TEXTURE_RGB_ARB or 
        WGL_BIND_TO_TEXTURE_RGBA_ARB must be TRUE. Create the pbuffer 
        with this pixel format. Set the pbuffer width and height to the 
        width and height of the level zero image. Set WGL_TEXTURE_FORMAT_ARB 
        to be WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB. Also set 
        WGL_TEXTURE_TARGET_ARB to WGL_TEXTURE_CUBE_MAP_ARB. 

    3)  Create a context for the pbuffer. Make the context current to the 
        pbuffer and initialize the context's attributes. 

    4)  Render all the cube map faces to the pbuffer. Call 
        wglSetPbufferAttribARB to set the cube map face before rendering
        each face. Call glFlush. 

    5)  Create a context for the window. Make the context current to the 
        window and intialize the contexts attributes. Bind a texture object 
        to the TEXTURE_CUBE_MAP_ARB target and set the texture parameters 
        to the desired values. 

    6)  Call wglBindTexImageARB to bind the pbuffer drawable to the cube 
        map texture. Set <iBuffer> to WGL_FRONT or WGL_BACK depending upon
        which color buffer was used for rendering the cube map.

    7)  Render to the window using the cube map texture. 

    8)  Call wglReleaseTexImageARB to release the color buffer of the 
        pbuffer. Goto step 4 to generate more frames. 

    To define a 2D texture, single threaded case 

    In step 2, set the WGL_TEXTURE_TARGET_ARB to WGL_TEXTURE_2D_ARB.

    Since a 2D texture does not have multiple faces, in step 5
    there is no need to call wglSetPbufferAttribARB. 

    In addition, if mipmaps are to be generated, the step 5 should
    be repeated multiple times with calls to wglSetPbufferAttribARB
    to set different mip levels.

New Procedures and Functions 

    BOOL wglBindTexImageARB (HPBUFFERARB hPbuffer, int iBuffer)

    BOOL wglReleaseTexImageARB (HPBUFFERARB hPbuffer, int iBuffer) 

    BOOL wglSetPbufferAttribARB (HPBUFFERARB hPbuffer, 
        const int *piAttribList) 

New Tokens 

    Accepted by the <piAttributes> parameter of wglGetPixelFormatAttribivARB, 
    wglGetPixelFormatAttribfvARB, and the <piAttribIList> and <pfAttribIList>
    parameters of wglChoosePixelFormatARB: 

        WGL_BIND_TO_TEXTURE_RGB_ARB         0x2070
        WGL_BIND_TO_TEXTURE_RGBA_ARB        0x2071

    Accepted by the <piAttribList> parameter of wglCreatePbufferARB and
    by the <iAttribute> parameter of wglQueryPbufferARB: 

        WGL_TEXTURE_FORMAT_ARB              0x2072
        WGL_TEXTURE_TARGET_ARB              0x2073
        WGL_MIPMAP_TEXTURE_ARB              0x2074

    Accepted as a value in the <piAttribList> parameter of 
    wglCreatePbufferARB and returned in the value parameter of
    wglQueryPbufferARB when <iAttribute> is WGL_TEXTURE_FORMAT_ARB: 

        WGL_TEXTURE_RGB_ARB                 0x2075
        WGL_TEXTURE_RGBA_ARB                0x2076
        WGL_NO_TEXTURE_ARB                  0x2077

    Accepted as a value in the <piAttribList> parameter of 
    wglCreatePbufferARB and returned in the value parameter of
    wglQueryPbufferARB when <iAttribute> is WGL_TEXTURE_TARGET_ARB: 

        WGL_TEXTURE_CUBE_MAP_ARB            0x2078
        WGL_TEXTURE_1D_ARB                  0x2079
        WGL_TEXTURE_2D_ARB                  0x207A
        WGL_NO_TEXTURE_ARB                  0x2077

    Accepted by the <piAttribList> parameter of wglSetPbufferAttribARB and 
    by the <iAttribute> parameter of wglQueryPbufferARB: 

        WGL_MIPMAP_LEVEL_ARB                0x207B
        WGL_CUBE_MAP_FACE_ARB               0x207C

    Accepted as a value in the <piAttribList> parameter of 
    wglSetPbufferAttribARB and returned in the value parameter of
    wglQueryPbufferARB when <iAttribute> is WGL_CUBE_MAP_FACE_ARB: 

        WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB     0x207D
        WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB     0x207E
        WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB     0x207F
        WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB     0x2080
        WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB     0x2081 
        WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB     0x2082

    Accepted by the <iBuffer> parameter of wglBindTexImageARB and 
    wglReleaseTexImageARB: 

        WGL_FRONT_LEFT_ARB                  0x2083
        WGL_FRONT_RIGHT_ARB                 0x2084
        WGL_BACK_LEFT_ARB                   0x2085
        WGL_BACK_RIGHT_ARB                  0x2086
        WGL_AUX0_ARB                        0x2087 
        WGL_AUX1_ARB                        0x2088 
        WGL_AUX2_ARB                        0x2089 
        WGL_AUX3_ARB                        0x208A 
        WGL_AUX4_ARB                        0x208B 
        WGL_AUX5_ARB                        0x208C 
        WGL_AUX6_ARB                        0x208D
        WGL_AUX7_ARB                        0x208E 
        WGL_AUX8_ARB                        0x208F 
        WGL_AUX9_ARB                        0x2090

Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 

    None. 

Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 

    None. 

Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 
Operations and the Frame Buffer) 

    None. 

Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 

    None. 

Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State 
Requests) 

    None. 

Additions to the WGL Specification 

    Add to the description of <piAttributes> in wglGetPixelFormatAttribivARB 
    and <pfAttributes> in wglGetPixelFormatfv: 

        WGL_BIND_TO_TEXTURE_RGB_ARB
        WGL_BIND_TO_TEXTURE_RGBA_ARB

        True if the color buffers can be bound to a RGB/RGBA texture. 
        Currently only pbuffers can be bound as textures so this attribute 
        will only be TRUE if WGL_DRAW_TO_PBUFFER is also TRUE. It is
        possible to bind a RGBA visual to a RGB texture in
        which case the values in the alpha component of the visual
        are ignored when the color buffer is used as a RGB texture.

        Implementations may choose not to support WGL_BIND_TO_TEXTURE_RGB_ARB
        for RGBA visuals.

    Add new table entries to match criteria in description of 
    wglChoosePixelFormatARB: 

        Attribute                       Type             Match Criteria 

        WGL_BIND_TO_TEXTURE_RGB_ARB     boolean             exact
        WGL_BIND_TO_TEXTURE_RGBA_ARB    boolean             exact

    Modify wglCreatePbufferARB: 

        HPBUFFERARB wglCreatePbufferARB (HDC hDC, int iPixelFormat, 
            int iWidth, int iHeight, const int *piAttribList); 

        ... 

        <iWidth> and <iHeight> specify the pixel width and height of the 
        rectangular pbuffer. If the texture format is set to
        WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB using 
        WGL_TEXTURE_FORMAT_ARB, then the pbuffer width and height 
        specify the size of the level zero texture image or, in the 
        case of a cube map texture, each level zero image. 

        <piAttribList> is a list of attribute {type, value} pairs containing 
        integer attribute values.  All of the attributes in <piAttribList>
        are followed by the corresponding required value. The list is 
        terminated with a value of 0. 

        <piAttribList> may be NULL or empty in which case all attributes assume
        their default values as described below. 

        The following attributes are supported by wglCreatePbufferARB: 

        WGL_TEXTURE_FORMAT_ARB

        This attribute indicates the format of the texture that will be
        created when a pbuffer is bound to a texture map.
        It can be set to WGL_TEXTURE_RGB_ARB, WGL_TEXTURE_RGBA_ARB or
        WGL_NO_TEXTURE_ARB. The default value is WGL_NO_TEXTURE_ARB.

        WGL_TEXTURE_TARGET_ARB 

        This attribute indicates the target for the texture that will be 
        created when the pbuffer is created with a texture format of
        WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB.  This attribute can
        be set to WGL_NO_TEXTURE_ARB, WGL_TEXTURE_1D_ARB, WGL_TEXTURE_2D_ARB 
        or WGL_TEXTURE_CUBE_MAP_ARB. The default value is WGL_NO_TEXTURE_ARB. 

        WGL_MIPMAP_TEXTURE_ARB 

        If this attribute is set to a non-zero value, and the texture format 
        is set to WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB, then storage 
        for mipmaps will be allocated. The default value is FALSE. 

        WGL_PBUFFER_LARGEST_ARB 

        If this attribute is set to a non-zero value, the largest 
        available pbuffer is allocated when the allocation of the pbuffer 
        would otherwise fail due to insufficient resources.  The width or 
        height of the allocated pbuffer never exceeds <iWidth> and <iHeight>, 
        respectively. Also, if the pbuffer will be used as a texture 
        (i.e., the value of the WGL_TEXTURE_TARGET_ARB attribute is
        WGL_TEXTURE_1D_ARB, WGL_TEXTURE_2D_ARB or WGL_TEXTURE_CUBE_MAP_ARB
        and texture format is WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB),
        then the aspect ratio will be preserved and the new width and 
        height will be valid sizes for the corresponding texture target. 
        (e.g. Both the width and height will be a power of 2 if the 
        implementation only supports power of 2 textures. Similarily, 
        the width and height will be equal for a cube map texture). 
        Use wglQueryPbufferARB to retrieve the dimensions of the 
        allocated pbuffer. The default value for this attribute is FALSE. 

        The resulting pbuffer will contain color buffers and ancillary 
        buffers as specified by <iPixelFormat>.  Note that pbuffers use 
        framebuffer resources so applications should consider deallocating 
        them when they are not in use. 

        It is possible to create a pbuffer with back buffers and to swap the 
        front and back buffers by calling wglSwapLayerBuffers.  The 
        contents of the back buffers after the swap depends on the 
        <iPixelFormat>.  (Pbuffers are the same as windows in this respect.) 

        The contents of the depth and stencil buffers may not be preserved 
        when rendering a texture to the pbuffer and switching which image 
        of the texture is rendered to (e.g., switching from rendering one 
        mipmap level to rendering another). 

        When wglCreatePbufferARB fails to create a pbuffer, NULL is returned.
        To get extended error information, call GetLastError. Possible 
        errors are as follows: 

        ERROR_INVALID_PIXEL_FORMAT  Pixel format is not valid. 

        ERROR_NO_SYSTEM_RESOURCES   Insufficient resources exist. 

        ERROR_INVALID_DATA          <iWidth> or <iHeight> is negative or zero. 

        ERROR_INVALID_DATA          WGL_TEXTURE_TARGET_ARB attribute is 
                                    set to WGL_TEXTURE_CUBE_MAP_ARB, and 
                                    iWidth does not equal iHeight.

        ERROR_INVALID_DATA          WGL_TEXTURE_TARGET_ARB attribute is set 
                                    to WGL_TEXTURE_1D_ARB, and iHeight is 
                                    not set to one. 

        ERROR_INVALID_DATA          The pixel format attribute 
                                    WGL_TEXTURE_FORMAT_ARB is 
                                    WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB
                                    and WGL_PBUFFER_WIDTH and/or 
                                    WGL_PBUFFER_HEIGHT specify an invalid 
                                    size for the implementation (e.g., the 
                                    texture size is not a power of 2). 

        ERROR_INVALID_DATA          An attribute in <piAttribList> is not a 
                                    valid attribute.

        ERROR_INVALID_DATA          The texture format is set to 
                                    WGL_NO_TEXTURE_ARB and texture target
                                    is set to something other than 
                                    WGL_NO_TEXTURE_ARB.

        ERROR_INVALID_DATA          The texture format is set to some target
                                    besides WGL_NO_TEXTURE_ARB and texture 
                                    target is set to WGL_NO_TEXTURE_ARB.

        .... 

    Modify wglDestroyPbufferARB: 

        A pbuffer is destroyed by calling 

        BOOL wglDestroyPbufferARB(HPBUFFERARB hPbuffer); 

        The pbuffer is destroyed once it is no longer current to any 
        rendering context and once all color buffers that are bound to a
        texture object have been released.  When a pbuffer is destroyed, 
        any memory resources that are attached to it are freed
        and its handle is no longer valid. 

        ....

    Add wglSetPbufferAttribARB: 

        To set an attribute of a pbuffer call 

        BOOL wglSetPbufferAttribARB (HPBUFFERARB hPbuffer, 
                                     const int *piAttribList); 

        with <hPbuffer> set to a previously returned pbuffer handle. 
        <piAttribList> is a list of attribute {type, value} pairs containing
        integer values. All the attributes in <piAttribList> are followed by 
        the corresponding desired value. The list is terminated with 0. 
        If <piAttribList> is NULL or empty then this function is a no-op. 

        The following values are accepted: 

        WGL_MIPMAP_LEVEL_ARB 

        For mipmap textures, this attribute indicates which level of the 
        mipmap should be rendered. The default value is zero. If the value
        of this attribute is outside the range of supported mipmap level, 
        the closest valid mipmap level is selected for rendering.

        WGL_CUBE_MAP_FACE_ARB 

        For cube map textures, this attribute indicates which face of the 
        cube map should be rendered; it must be set to one of 

        WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB, 
        WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB, 
        WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB, 
        WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB, 
        WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB, 
        WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB.

        The default value is WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB. 

        If wglSetPbufferAttribARB fails, FALSE is returned.  To get extended
        error information, call GetLastError. Possible errors are as follows: 

        ERROR_INVALID_HANDLE        <hPbuffer> is not a valid handle. 

        ERROR_INVALID_DATA          Bad attribute specified in <piAttribList>.

        ERROR_INVALID_DATA          WGL_MIPMAP_LEVEL_ARB does not specify
                                    a valid mipmap level.

        ERROR_INVALID_DATA          WGL_CUBE_MAP_IMAGE_ARB is not set to a
                                    valid value.

        ....

    Modify wglQueryPbufferARB: 

        To query an attribute associated with a specific pbuffer, call 

        BOOL wglQueryPbufferARB(HPBUFFERARB hPbuffer, int iAttribute, 
                                int *piValue); 

        with <hPbuffer> set to a previously returned pbuffer handle. 
        <iAttribute> must be set to one of WGL_PBUFFER_WIDTH_ARB, 
        WGL_PBUFFER_HEIGHT_ARB, WGL_PBUFFER_LOST_ARB, WGL_TEXTURE_TARGET_ARB, 
        WGL_MIPMAP_TEXTURE_ARB, WGL_MIPMAP_LEVEL_ARB, WGL_CUBE_MAP_FACE_ARB
        or WGL_TEXTURE_FORMAT_ARB.

        The WGL_PBUFFER_LOST_ARB query can be used to determine if the pixel 
        buffer memory was lost due to a display mode change.  A value of 
        TRUE is returned in buffer <piValue> if the display mode change lost  
        the memory for the pixel buffer. It is not an error to render to a 
        pixel buffer in this state, but the effect of rendering to it is the
        same as if the pixel buffer was destroyed:  the context state will 
        be updated, but the values of the returned pixels are undefined.  
        The pixel buffer must be destroyed and recreated if the pixel buffer
        memory has been lost.  A value of FALSE is returned to indicate 
        that the contents of the pixel buffer are unaffected by the display 
        mode change. 

        When a color buffer of a pbuffer is bound as a texture, then the 
        contents of that texture must be preserved until the color buffer is 
        released. If the pbuffer is lost, any color buffers that are bound 
        to textures will be freed when they are released back to the pbuffer
        by calling wglReleaseTexImage. 

        If  wglPbufferAttribARB fails, FALSE is returned.  To get extended 
        error information, call GetLastError. Possible errors are as follows: 

        ERROR_INVALID_HANDLE        <hPbuffer> is not a valid handle. 

        ERROR_INVALID_DATA          <iAttribute> is not a valid attribute.

        .... 

    Add wglBindTexImageARB and wglReleaseTexImageARB: 

        The command 

        BOOL wglBindTexImageARB (HPBUFFERARB hPbuffer, int iBuffer)

        defines a one-dimensional texture image or two-dimensional 
        texture image or a set of two-dimensional cube map texture images.  
        The texture image or images consist of the image data in <iBuffer>
        for the specified pbuffer, <hPbuffer>, and need not be copied.
        The texture target, the texture format and the size of the 
        texture components are derived from attributes of pbuffer 
        specified by <hPbuffer>. 
        
        Note that any existing images associated with the different 
        mipmap levels of the texture object are freed (it is as if 
        TexImage was called with an image of zero width).

        The pbuffer attribute WGL_TEXTURE_FORMAT_ARB determines the base 
        internal format of the texture. The component sizes are also 
        determined by pbuffer attributes as shown in the table below. 
  
        Texture Component           Size

            R                   WGL_RED_BITS_ARB
            G                   WGL_GREEN_BITS_ARB
            B                   WGL_BLUE_BITS_ARB
            A                   WGL_ALPHA_BITS_ARB


        Table x.x: Size of texture components 

        The texture targets are derived from the WGL_TEXTURE_TARGET_ARB 
        attribute of <hPbuffer>. If the texture target for the pbuffer is 
        WGL_TEXTURE_CUBE_MAP_ARB then <iBuffer> defines a set of cubemap 
        images for the cube map texture objects which are bound to the 
        current context (hereafter referred to as the current texture 
        object).  Note that when the texture target is 
        WGL_TEXTURE_CUBE_MAP_ARB, all cube map texture targets are defined
        by a single call to wglBindTexImageARB. If the texture target is 
        WGL_TEXTURE_2D_ARB, then <iBuffer> defines a 2D texture for the 
        current 2D texture object; if the texture target is WGL_TEXTURE_1D_ARB, 
        then <iBuffer> defines a 1D texture for the current 1D texture object. 

        The possible values for <iBuffer> are WGL_FRONT_LEFT_ARB, 
        WGL_FRONT_RIGHT_ARB, WGL_BACK_LEFT_ARB, WGL_BACK_RIGHT_ARB, and 
        WGL_AUX0_ARB through WGL_AUXn_ARB. 

        If <hPbuffer> is the calling thread's current drawable, 
        wglBindTexImageARB performs an implicit glFlush. 

        After this function is called, the pbuffer associated with <iBuffer> 
        is no longer available for reading or writing. Any read
        operation, such as glReadPixels, which reads values from any of the 
        pbuffer's color buffers or ancillary buffers, will produce 
        indeterminate results. In addition, any draw operation that is 
        done to the pbuffer prior to wglReleaseTexImageARB being called, 
        produces indeterminant results.  Specifically, if the pbuffer is 
        current to a context and thread then rendering commands will be 
        processed and the context state will be updated but the pbuffer may 
        or may not be written. Also, SwapBuffers is a no-op if it is called 
        on this pbuffer. 

        Note that the color buffer is bound to a texture object. If the
        texture object is shared between contexts, then the 
        color buffer is also shared. If a texture object is deleted
        before wglReleaseTexImageARB is called, then the color buffer is 
        released and the pbuffer is made available for reading and writing. 

        It is not an error to call TexImage2D, TexImage1D, 
        CopyTexImage1D or CopyTexImage2D to replace an image of a texture 
        object that has a color buffer bound to it. However, these calls 
        will cause the color buffer to be released back to the pbuffer and 
        new memory will be allocated for the texture. Note that the color 
        buffer is released even if the image that is being defined is a 
        mipmap level that was not defined by the color buffer. 

        wglBindTexImageARB is ignored if there is no current rendering 
        context. 

        If  wglBindTexImageARB fails, FALSE is returned.  To get extended 
        error information, call GetLastError. Possible errors are as follows: 

        ERROR_INVALID_HANDLE        <hPbuffer> is not a valid handle. 

        ERROR_INVALID_DATA          <iBuffer> is not a valid value. 

        ERROR_INVALID_OPERATION     The pbuffer attribute 
                                    WGL_TEXTURE_FORMAT_ARB is set to
                                    WGL_NO_TEXTURE_ARB.

        ERROR_INVALID_OPERATION     <iBuffer> is already bound to the texture


    To release a color buffer that is being used as a texture call 

        BOOL wglReleaseTexImageARB (HPBUFFERARB hPbuffer, int iBuffer) 

        This releases the specified color buffer back to the pbuffer. The 
        pbuffer is made available for reading and writing when it no
        longer has any color buffers bound as textures. 

        <iBuffer> must be one of WGL_FRONT_LEFT_ARB, WGL_FRONT_RIGHT_ARB, 
        WGL_BACK_LEFT_ARB, WGL_BACK_RIGHT_ARB, or WGL_AUX0_ARB through 
        WGL_AUXn_ARB. 

        The contents of the color buffer are undefined when it is first 
        released. In particular there is no guarantee that the texture
        image is still present. However, the contents of other color 
        buffers is unaffected by this call. Also, the contents of the depth,
        stencil and accumulation buffers are not affected by 
        wglBindTexImageARB and wglReleaseTexImageARB. 
        
        If the specified color buffer is no longer bound to a texture (e.g.,
        because the texture object was deleted) then this call is a
        noop; no error is generated. 

        After a color buffer is released from a texture (either explicitly
        by calling wglReleaseTexImageARB or implicitly by calling a 
        routine such as TexImage2D), all texture images that were defined
        by the color buffer become NULL (it is as if TexImage was 
        called with an image of zero width).

        If  wglReleaseTexImageARB fails, FALSE is returned. To get extended 
        error information, call GetLastError. Possible errors are as follows: 

        ERROR_INVALID_HANDLE        <hPbuffer> is not a valid handle. 

        ERROR_INVALID_DATA          <iBuffer> is not a valid value. 
        
        ERROR_INVALID_OPERATION     The pbuffer attribute 
                                    WGL_TEXTURE_FORMAT_ARB is set to
                                    WGL_NO_TEXTURE_ARB.

New State 

    None 

Dependencies on GL_ARB_texture_cube_map 

    If GL_ARB_texture_cube_map is not supported then all references to
    WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB,
    WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB,
    WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB, 
    WGL_TEXTURE_CUBE_MAP_ARB and WGL_CUBE_MAP_FACE_ARB are deleted. 
  
Revision History 
    07/16/01    bpoddar     1. Added WGL_TEXTURE_CUBE_MAP_POSITIVE_*_ARB 
                               enums to the new tokens section.
                            2. Added clarification on MIPMAP_LEVEL_ARB usage.
                            3. Removed 1 invalid error condition from
                               wglBindTexImage.
                            4. Changed parameter references to <parameter>.

    07/12/01    bpoddar     Fixed minor typos and added enum values.
        
    06/22/01    bpoddar     Minor language edits from ARB participants.

    04/09/01    bpoddar     1. Renamed WGL_TEXTURE_TYPE_ARB to 
                               WGL_TEXTURE_TARGET_ARB.
                            2. Cleaned up behavior of WGL_TEXTURE_FORMAT_ARB.

    03/23/01    bpoddar     1. Updated the implementation notes section
                               with the discussion at the ARB. 
                            2. Replaced ERROR_??? with specified errors
                            3. Clarified width and height selection rules
                               for WGL_PBUFFER_LARGEST.
                            4. Added policy for dealing with mip levels
                               both on Bind and Release.
                            5. Specified behavior for implicit release and
                               added comment to implementation section.
                            6. Added couple of errors to SetPbufferAttrib. 

    03/06/01    bpoddar     1. Deleted references to 3D texture
                            2. Deleted references to LUMINANCE, INTENSITY
                               textures.
                            3. wglBindTexImageARB no longer provides a
                               separate mipmap attribute (issue #21).
                            4. Removed references to multiple texture 
                               objects for cube maps.
                            5. Added issue # 23.
                            6. Added implementation notes section.

    12/01/00    pwomack     Updated issues list. Require non-static pbuffer 
                            attributes to be set via SetPbufferAttrib (they 
                            cannot be set when the pbuffer is created.) 
                            The WGL_TEXTURE_TARGET_ARB attribute now takes 
                            WGL_NO_TEXTURE_ARB as a value, so the app can 
                            indicate that the pbuffer will never be bound 
                            as a texture. If a pbuffer is created with 
                            WGL_TEXTURE_TARGET_ARB set to WGL_NO_TEXTURE_ARB, 
                            then an error results if an attempt is made to 
                            bind it as a texture. Specified default values 
                            for all attribute lists. When a color buffer is 
                            bound as a texture then drawing to the pbuffer 
                            gives undefined results (previously the 
                            rendering was lost). When a color buffer is 
                            bound as a texture, calling TexImage or 
                            CopyTexImage releases the color buffer back to 
                            the pbuffer. 

    11/12/00    pwomack     Created. Copied from GLX extension. Added WGL 
                            calls and removed all GLX-centric stuff.