WGL_AMD_gpu_association.txt

Name

    AMD_gpu_association
 
Name Strings

    WGL_AMD_gpu_association

Contact

    Nick Haemel, AMD (nick.haemel 'at' amd.com)

Status

    Complete

Version

    Last Modified Date: March 03, 2009
    Author Revision: 1.0
    
    Based on:  WGL_ARB_make_current_read specification
               Date: 3/15/2000   Version: 1.1
               
               EXT_framebuffer_object specification
               Date: 2/13/2007   Revision #119

Number

    361

Dependencies

    OpenGL 1.5 is required.
    
    WGL_ARB_extensions_string is required.
    
    GL_EXT_framebuffer_object is required.

    This extension interacts with WGL_ARB_make_current_read.

    This extension interacts with GL_EXT_framebuffer_blit.
    
    This extension interacts with WGL_ARB_create_context.


Overview


    There currently is no way for applications to efficiently use GPU
    resources in systems that contain more than one GPU. Vendors have 
    provided methods that attempt to split the workload for an 
    application among the available GPU resources. This has proven to be 
    very inefficient because most applications were never written with 
    these sorts of optimizations in mind. 
    
    This extension provides a mechanism for applications to explicitly
    use the GPU resources on a given system individually. By providing 
    this functionality, a driver allows applications to make appropriate
    decisions regarding where and when to distribute rendering tasks.
    
    The set of GPUs available on a system can be queried by calling 
    wglGetGPUIDsAMD(). The current GPU assigned to a specific context 
    can be determined by calling wglGetContextGPUIDAMD. Each GPU in a 
    system may have different performance characteristics in addition 
    to supporting a different version of OpenGL. The specifics of each
    GPU can be obtained by calling wglGetGPUInfo. This will allow 
    applications to pick the most appropriate GPU for each rendering 
    task.
    
    Once all necessary GPU information has been obtained, a context tied
    to a specific GPU can be created with wglCreateAssociatedContextAMD.
    These associated contexts can be made current with  
    wglMakeAssociatedContextCurrentAMD and deleted with 
    wglDeleteAssociatedContextAMD. Only one GPU associated or 
    non-associated context can be current at one time per thread. 
    
    To provide an accelerated path for blitting data from one context
    to another, the new blit function BlitContextFramebufferAMD has 
    been added.
    
    


New Procedures and Functions

    UINT  wglGetGPUIDsAMD(UINT maxCount, UINT *ids);
    
    INT   wglGetGPUInfoAMD(UINT id, INT property, GLenum dataType,
                           UINT size, void *data)
    
    UINT  wglGetContextGPUIDAMD(HGLRC hglrc);
    
    HGLRC wglCreateAssociatedContextAMD(UINT id);
    
    HGLRC wglCreateAssociatedContextAttribsAMD(UINT id, HGLRC hShareContext,
				                               const int *attribList);
				     
    BOOL  wglDeleteAssociatedContextAMD(HGLRC hglrc);

    BOOL  wglMakeAssociatedContextCurrentAMD(HGLRC hglrc);
    
    HGLRC wglGetCurrentAssociatedContextAMD(void);
        
    VOID  wglBlitContextFramebufferAMD(HGLRC dstCtx, GLint srcX0, GLint srcY0,
                                       GLint srcX1, GLint srcY1, GLint dstX0,
                                       GLint dstY0, GLint dstX1, GLint dstY1,
                                       GLbitfield mask, GLenum filter);

New Tokens

    Accepted by the <property> parameter of wglGetGPUInfo:

      WGL_GPU_VENDOR_AMD                 0x1F00
      WGL_GPU_RENDERER_STRING_AMD        0x1F01
      WGL_GPU_OPENGL_VERSION_STRING_AMD  0x1F02
      WGL_GPU_FASTEST_TARGET_GPUS_AMD    0x21A2
      WGL_GPU_RAM_AMD                    0x21A3
      WGL_GPU_CLOCK_AMD                  0x21A4
      WGL_GPU_NUM_PIPES_AMD              0x21A5
      WGL_GPU_NUM_SIMD_AMD               0x21A6
      WGL_GPU_NUM_RB_AMD                 0x21A7
      WGL_GPU_NUM_SPI_AMD                0x21A8

    Accepted by the <dataType> argument of wglGetGPUInfoAMD:

      GL_UNSIGNED_BYTE
      GL_UNSIGNED_INT
      GL_INT
      GL_FLOAT

    Accepted by the <mask> argument of wglBlitContextFramebufferAMD:

      GL_COLOR_BUFFER_BIT
      GL_DEPTH_BUFFER_BIT
      GL_STENCIL_BUFFER_BIT


Additions to the GLX Specification

    This specification is written for WGL.


GLX Protocol

    This specification is written for WGL.    


Additions to the WGL Specification

    GPU Associated Contexts
    
    When multiple GPUs are present, a context can be created for 
    off-screen rendering that is associated with a specific GPU. 
    This will allow applications to achieve an app-specific 
    distributed GPU utilization.
    
    The IDs for available GPUs can be queried with the command:
    
        UINT  wglGetGPUIDsAMD(UINT maxCount, UINT *ids);
    
    where <maxCount> is the max number of IDs that can be returned and
    <ids> is the array of returned IDs. If the function succeeds, 
    the return value is the number of total GPUs available. The 
    value 0 is returned if no GPUs are available or if the call has 
    failed. The array pointer <ids> passed into the function will be 
    populated by the smaller of maxCount or the total GPU count 
    available. The ID 0 is reserved and will not be retuned as a 
    valid GPU ID. If the array <ids> is NULL, the function will 
    only return the total number of GPUs. <ids> will be tightly packed
    with no 0 values between valid ids.
    
    Calling wglGetGPUIDsAMD once with <maxCount> set to zero returns 
    the total available GPU count which can be used to allocate an 
    appropriately sized id array before calling wglGetGPUIDsAMD 
    again to query the full set of supported GPUs.

    Each GPU in a system may have different properties, performance 
    characteristics and different supported OpenGL versions. To 
    determine which GPU is best suited for a specific task the 
    following functions may be used:
        
        INT  wglGetGPUInfoAMD(UINT id, INT property, GLenum dataType,
                              UINT size, void *data);

    <id> is a GPU id obtained from calling wglGetGPUIDsAMD. The GPU ID 
    must be a valid GPU ID. The function will fail if <id> is an invalid
    GPU ID and -1 will be returned. <property> is the information being
    queried. <dataType> may be GL_UNSIGNED_INT, GL_INT, GL_FLOAT, or 
    GL_UNSIGNED_BYTE and signals what data type is to be returned. <size>
    signals the size of the data buffer passed into wglGetGPUInfoAMD. 
    This is the count of the array of type <dataType>. <data> is the 
    buffer which will be filled with the requested information. For a 
    string, <size> will be the number of characters allocated and will 
    include NULL termination. For arrays of type GL_UNSIGNED_INT, GL_INT, 
    and GL_FLOAT <size> will be the array depth. If the function 
    succeeds, the number of values written will be returned. If the number
    of values written is equal to <size>, the query should be repeated with
    a larger <data> buffer. Strings should be queried using the
    GL_UNSIGNED_BYTE type, are UTF-8 encoded and will be NULL terminated.
    If the function fails, -1 will be returned. 

    <property> defines the GPU property to be queried, and may be one of
    WGL_GPU_OPENGL_VERSION_STRING_AMD, WGL_GPU_RENDERER_STRING_AMD,
    WGL_GPU_FASTEST_TARGET_GPUS_AMD, WGL_GPU_RAM_AMD, WGL_GPU_CLOCK_AMD,
    WGL_GPU_NUM_PIPES_AMD, WGL_GPU_NUM_SIMD_AMD, WGL_GPU_NUM_RB_AMD, or
    WGL_GPU_NUM_SPI_AMD.

    If <size> is not sufficient to hold the entire value for a particular
    property, the number of values returned will equal <size>. If 
    <dataType> is inappropriate for <property>, for instance INT for a 
    property which is a string, the function will fail and -1 will be 
    returned.

    Querying WGL_GPU_OPENGL_VERSION_STRING_AMD returns the highest supported 
    OpenGL version string and WGL_GPU_RENDERER_STRING_AMD returns name 
    of the GPU. <dataType> must be GL_UNSIGNED_BYTE with the previous 
    properties. Querying WGL_GPU_FASTEST_TARGET_GPUS_AMD returns an array 
    of the IDs of GPUs with the fastest data blit rates when using 
    wglBlitContextFramebufferAMD. This list is ordered fastest 
    first. This provides a performance hint about which contexts and GPUS
    are capable of transfering data between each other the quickest. Querying 
    WGL_GPU_RAM_AMD returns the amount of RAM available to GPU in MB. Querying 
    WGL_GPU_CLOCK_AMD returns the GPU clock speed in MHz.  Querying 
    WGL_GPU_NUM_PIPES_AMD returns the nubmer of 3D pipes. Querying 
    WGL_GPU_NUM_SIMD_AMD returns the number of SIMD ALU units in each 
    shader pipe. Querying WGL_GPU_NUM_RB_AMD returns the number of render 
    backends. Querying WGL_GPU_NUM_SPI_AMD returns the number of shader 
    parameter interpolaters. If the <parameter> being queried is not 
    applicable for the GPU specified by <id>, the value 0 will be returned.

    Unassociated contexts are created by calling wglCreateContext. 
    Although these contexts are unassociated, their use will still be 
    tied to a single GPU in most cases. For this reason it is advantageous 
    to be able to query the GPU an existing unassociated context resides 
    on. If multiple GPUs are available, it would be undesirable 
    to use one for rendering to visible surfaces and then chose the 
    same one for off-screen rendering. Use the following command to 
    determine which GPU a context is attached to:
    
        UINT  wglGetContextGPUIDAMD(HGLRC hglrc);
    
    <hglrc> is the context for which the GPU id will be returned. If the 
    context is invalid or if an error has occurred, wglGetContextGPUIDAMD 
    will return 0.
    
    To create an associated context, use:
    
        HGLRC wglCreateAssociatedContextAMD(UINT id);
    
    <id> must be a valid GPU id and cannot be 0. If a context was 
    successfully created the handle will be returned by 
    wglCreateAssociatedContextAMD. If a context could not be created, NULL 
    will be returned. If a context could not be created, error information 
    can be obtained by calling GetLastError. Upon successful creation,
    no pixel format is tied to an associated context.
    
    To create an associated context and request a specific GL version, use:
    
        HGLRC wglCreateAssociatedContextAttribsAMD(UINT id, 
                    HGLRC hShareContext, const int *attribList)
    
    All capabilities and limitations of wglCreateContextAttribsARB apply 
    to wglCreateAssociatedContextAttribsAMD. Additionally, <id> must be 
    a valid GPU ID and cannot be 0. If a context was successfully created 
    the handle will be returned by wglCreateAssociatedContextAttribsAMD. 
    If a context could not be created, NULL will be returned. In this 
    case, error information can be obtained by calling GetLastError. Upon 
    successful creation, no pixel format is tied to an associated context.
    
    <hShareContext> must either be NULL or that of an associated context 
    created with the the same GPU ID as <id>. If <hShareContext> was 
    created using a different ID, wglCreateAssociatedContextAttribsAMD 
    will fail and return NULL.

    
    A context must be deleted once it is no longer needed. Use the 
    following call to delete an associated context:
    
        BOOL wglDeleteAssociatedContextAMD(HGLRC hglrc);
    
    If the function succeeds, TRUE will be returned, otherwise FALSE is 
    returned. <hglrc> must be a valid associated context created by 
    calling wglCreateAssociatedContextAMD. If an unassociated context, 
    created by calling wglCreateContext, is passed into <hglrc>, the 
    function will fail. An associated context cannot be deleted by calling
    wglDeleteContext. If an associated context is passed into 
    wglDeleteContext, the result is undefiend.
    
    To render using an associated context, it must be made the current 
    context for a thread: 
        
        BOOL  wglMakeAssociatedContextCurrentAMD(HGLRC hglrc);
    
    <hglrc> is a context handle created by calling 
    wglCreateAssociatedContextAMD. If <hglrc> was created using 
    wglCreateContext, the call will fail and FALSE will be returned. If 
    <hglrc> is not a valid context and not NULL, the call will fail and 
    FALSE will be returned. If the call succeeds, TRUE will be returned. 
    To detach the current associated context, pass NULL as <hglrc>.
    
    Only one type of context can be current to a thread at a time. If an
    unassociated context is current to a hdc when 
    wglMakeAssociatedContextCurrentAMD is called with a valid <hglrc>, it 
    is as if wglMakeCurrent is called first with an hglrc of NULL. If an 
    associated context is current and wglMakeCurrent is called with a 
    valid context, it is as if wglMakeAssociatedContextCurrentAMD is 
    called with an hglrc of NULL.

    The current associated context can be queried by calling:
    
        HGLRC wglGetCurrentAssociatedContextAMD(void);
    
    The current associated context is returned on a successful call to 
    this function. If no associated context is current, NULL is returned. 
    If an unassociated context is current, NULL will be returned. 

    Associated contexts can be shared just as unassociated contexts can by 
    calling wglShareLists. Associated contexts can only be shared with 
    other contexts that were created with the same GPU id. Associated 
    contexts cannot be shared with non-associated contexts. FALSE will be 
    returned if either context is not valid or not an associated context 
    associated with the same GPU.

    An associated context can not be passed in as a parameter into 
    wglCopyContext. If an associated context is passed into wglCopyContext,
    the result is undefiend.
    
    The addresses returned from wglGetProcAddress are only valid for the 
    current context. It may be invalid to use proc addresses obtained from
    a traditional context with an associated context. Furthermore, the 
    OpenGL version and extensions supported on an associated context may 
    differ. Each context should be treated seperately, proc addressses 
    should be queried for each after context creation.
    
    Calls to wglSwapBuffers and wglSwapLayerBuffers when an associated 
    context is current will return FALSE and will have no effect.
    
    There is no way to use pBuffers with associated contexts.
    
    Overlays and underlays are not supported with associated contexts.
    
    The same associated context is used for both write and read operations.
    
    To facilitate high performance data communication between multiple 
    contexts, a new function is necessary to blit data from one context 
    to another. 
    
    VOID  wglBlitContextFramebufferAMD(HGLRC dstCtx, GLint srcX0, GLint srcY0,
                                       GLint srcX1, GLint srcY1, GLint dstX0, 
                                       GLint dstY0, GLint dstX1, GLint dstY1, 
                                       GLbitfield mask, GLenum filter);

    <dstCtx> is the context handle for the write context. <mask> is the 
    bitwise OR of a number of values indicating which buffers are to be 
    copied. The values are GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, and 
    GL_STENCIL_BUFFER_BIT, which are described in section 4.2.3.  The 
    pixels corresponding to these buffers are copied from the source 
    rectangle, bound by the locations (srcX0, srcY0) and (srcX1, srcY1), 
    to the destination rectangle, bound by the locations (dstX0, dstY0) 
    and (dstX1, dstY1).  The lower bounds of the rectangle are inclusive, 
    while the upper bounds are exclusive. 

    The source context is the current GL context. Specifying the current 
    GL context as the <dstCtx> will result in the error 
    GL_INVALID_OPERATION being generated. If <dstCtx> is invalid, the
    error GL_INVALID_OPERATION will be generated. If no context is
    current at the time of this call, the error GL_INVALID_OPERATION
    will be generated. These errors may be queried by calling glGetError.
    The target framebuffer will be the framebuffer bound to 
    GL_DRAW_FRAMEBUFFER_EXT  in the context <dstCtx>. The source framebuffer 
    will be the framebuffer bound to GL_READ_FRAMEBUFFER_EXT in the 
    currently bound  context.

    The restrictions that apply to the source and destination rectangles 
    specified with <srcX0>, <srcY0>, <srcX1>, <srcY1>, <dstX0>, <dstY0>
    <dstX0>, and <dstY0> are the same as those that apply for 
    glBlitFramebufferEXT. The same error conditions exist as for
    glBlitFramebufferEXT.
    
    When called, this function will execute immediately in the currently 
    bound context. It is up to the caller to maintain appropriate 
    synchronization between the current context and <dstCtx> to ensure 
    rendering to the appropriate surfaces has completed on the current 
    and <dstCtx> contexts.

Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
Operations and the Frame Buffer)
Modify the beginning of section 4.4.1 as follows:

    When an assoicated context is bound, the default state for an associated 
    context is invalid for rendering. Because there is no attached window, 
    there is no default framebuffer surface to render to. An app created 
    framebuffer object must be bound for rendering to be valid. If the 
    object bound to GL_FRAMEBUFFER_BINDING_EXT is 0, it is as if the 
    framebuffer is incomplete, and an
    GL_INVALID_FRAMEBUFFER_OPERATION_EXT error will be generated
    where rendering is attempted.

    
New State

    None
        

Interactions with GL_EXT_framebuffer_blit

    If the framebuffer blit extension is not supported, all language 
    referring to glBlitFramebufferEXT and wglBlitContextFramebufferAMD 
    is removed.
    
Interactions with GL_EXT_framebuffer_object

    If WGL_AMD_gpu_association is supported, and context created with it 
    will also support EXT_framebuffer_object.


Interactions with WGL_ARB_make_current_read

    If the make current read extension is supported, it is invalid to pass 
    an associated context handle as a parameter to 
    wglMakeContextCurrentARB. If an associated context is passed into 
    wglMakeContextCurrentARB, the result is undefiend.

Interactions with WGL_ARB_create_context
    If wglCreateContextAttribsARB is not supported, all language 
    referring to wglCreateAssociatedContextAttribsAMD is removed.
    

Issues

1. Is a different DC necessary in addition to an associated context?
   
   - Resolved. It seems unnecessary. An associated DC would be a virtual 
   DC with no real meaning. Using an associated DC would require apps to 
   create windows and set pixelformats that are meaningless.

2. Should the list of IDs returned by wglGetGPUIDs be ordered in some 
   way? By fastest GPU?
   
   - Resolved. There is no need to create a restriction. The GPU info can 
   be queried.
   
3. What happens when the GPUs support different versions of OpenGL?
   Do we allow this? Do we need the 
   
   - Resolved. It is the applications responsibility to use each GPU 
   appropriately based on the supported version of OpenGL.
   
4. What should the relation between wglMakeAssociatedContextCurrentAMD and 
   wglMakeCurrent be? Should it be legal to have an associated context and a 
   normal context current to the same thread?
   
   - Resolved. It seems feasible to have an associated context and a normal 
   one both current, but for simplicity, only one of any type will be allowed 
   per thead.
   
5.  Will a call to wglShareLists with contexts that were not created through
    wglCreateContext make it through to the driver? If not, will a new 
    shareLists call be necessary?   
    
    -Resolved. This is not an issue.

6.  Is GPUClock a good parameter for the GPUInfo structure? How should 
    relative GPU performance be presented?
    
    - Resolved. This is sufficent. One alternative would be to test execution of 
    some amount of geometry rendering. But applications are better positioned
    to perform this based on their rendering needs.

7.  Is BlitContextFramebufferEXT the best way to transfer data from one 
    context to another? Or would it be better to create a read and write
    context bind point?
    
    - Resolved. Both methods would work well. Adding a new function prevents 
    the additional state that would have to be tracked for a global read and
    write bind point. In addition, using global (wgl) bind points may 
    introduce mutability issues when multiple threads are being used. 
    Only one thread could use the interface at a time. 

8.  Should the GPU ID be part of the pixel format? That would allow 
    apps to search for a format that worked on different GPUs. 
    
    - Resolved. Using the pixel format would provide a non-intrusive solution,
    but would require the app to use a DC that is not available through
    current interfaces. In addition, the app would have to create a 
    dummy window.

9.  Are there any problems calling wglShareLists with contexts not created
    by Windows?
    
    - Resolved. This is not an issue.

10. What should happen in an associated context when the default FBO is 
    bound? The 2 options seem to be 1. Throw an error and do not render,
    2. Discard all rendering as failing the pixel ownership test.
    
    - The first option seems more logical.


Revision History
    03/03/2009 - Initial version written. Written by nickh