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 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 argument of wglGetGPUInfoAMD: GL_UNSIGNED_BYTE GL_UNSIGNED_INT GL_INT GL_FLOAT Accepted by the 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 is the max number of IDs that can be returned and 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 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 is NULL, the function will only return the total number of GPUs. will be tightly packed with no 0 values between valid ids. Calling wglGetGPUIDsAMD once with 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); is a GPU id obtained from calling wglGetGPUIDsAMD. The GPU ID must be a valid GPU ID. The function will fail if is an invalid GPU ID and -1 will be returned. is the information being queried. may be GL_UNSIGNED_INT, GL_INT, GL_FLOAT, or GL_UNSIGNED_BYTE and signals what data type is to be returned. signals the size of the data buffer passed into wglGetGPUInfoAMD. This is the count of the array of type . is the buffer which will be filled with the requested information. For a string, will be the number of characters allocated and will include NULL termination. For arrays of type GL_UNSIGNED_INT, GL_INT, and GL_FLOAT 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 , the query should be repeated with a larger 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. 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 is not sufficient to hold the entire value for a particular property, the number of values returned will equal . If is inappropriate for , 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. 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 being queried is not applicable for the GPU specified by , 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); 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); 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, 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. must either be NULL or that of an associated context created with the the same GPU ID as . If 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. must be a valid associated context created by calling wglCreateAssociatedContextAMD. If an unassociated context, created by calling wglCreateContext, is passed into , 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); is a context handle created by calling wglCreateAssociatedContextAMD. If was created using wglCreateContext, the call will fail and FALSE will be returned. If 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 . 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 , 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); is the context handle for the write context. 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 will result in the error GL_INVALID_OPERATION being generated. If 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 . 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 , , , , , , and 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 to ensure rendering to the appropriate surfaces has completed on the current and 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