| Name |
| |
| AMD_gpu_association |
| |
| Name Strings |
| |
| GLX_AMD_gpu_association |
| |
| Contact |
| |
| David Mao, AMD (david.mao 'at' amd.com) |
| |
| Status |
| |
| Complete |
| |
| Version |
| |
| Last Modified Date: September 18, 2014 |
| Author Revision: 2 |
| |
| Based on: GLX_SGI_make_current_read specification |
| Date: 3/20/1997 |
| |
| EXT_framebuffer_object specification |
| Date: 2/13/2007 Revision #119 |
| |
| Number |
| |
| 398 |
| |
| Dependencies |
| |
| OpenGL 1.5 is required. |
| |
| GLX 1.3 is required. |
| |
| GL_EXT_framebuffer_object is required. |
| |
| GLX_ARB_get_proc_address is required. |
| |
| This extension interacts with GLX_SGI_make_current_read. |
| |
| This extension interacts with GL_EXT_framebuffer_blit. |
| |
| This extension interacts with GLX_ARB_create_context. |
| |
| This extension interacts with WGL_AMD_gpu_association. |
| |
| 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 |
| glXGetGPUIDsAMD. The current GPU assigned to a specific context |
| can be determined by calling glXGetContextGPUIDAMD. 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 glXGetGPUInfo. 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 glXCreateAssociatedContextAMD. |
| These associated contexts can be made current with |
| glXMakeAssociatedContextCurrentAMD and deleted with |
| glXDeleteAssociatedContextAMD. 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 |
| |
| unsigned int glXGetGPUIDsAMD(unsigned int maxCount, unsigned int *ids); |
| |
| int glXGetGPUInfoAMD(unsigned int id, int property, GLenum dataType, |
| unsigned int size, void *data) |
| |
| unsigned int glXGetContextGPUIDAMD(GLXContext ctx); |
| |
| GLXContext glXCreateAssociatedContextAMD(unsigned int id, |
| GLXContext share_list); |
| |
| GLXContext glXCreateAssociatedContextAttribsAMD(unsigned int id, |
| GLXContext share_context, |
| const int *attribList); |
| |
| Bool glXDeleteAssociatedContextAMD(GLXContext ctx); |
| |
| Bool glXMakeAssociatedContextCurrentAMD(GLXContext ctx); |
| |
| GLXContext glXGetCurrentAssociatedContextAMD(void); |
| |
| void glXBlitContextFramebufferAMD(GLXContext 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 glXGetGPUInfo: |
| |
| GLX_GPU_VENDOR_AMD 0x1F00 |
| GLX_GPU_RENDERER_STRING_AMD 0x1F01 |
| GLX_GPU_OPENGL_VERSION_STRING_AMD 0x1F02 |
| GLX_GPU_FASTEST_TARGET_GPUS_AMD 0x21A2 |
| GLX_GPU_RAM_AMD 0x21A3 |
| GLX_GPU_CLOCK_AMD 0x21A4 |
| GLX_GPU_NUM_PIPES_AMD 0x21A5 |
| GLX_GPU_NUM_SIMD_AMD 0x21A6 |
| GLX_GPU_NUM_RB_AMD 0x21A7 |
| GLX_GPU_NUM_SPI_AMD 0x21A8 |
| |
| Accepted by the <dataType> argument of glXGetGPUInfoAMD: |
| |
| GL_UNSIGNED_BYTE |
| GL_UNSIGNED_INT |
| GL_INT |
| GL_FLOAT |
| |
| Accepted by the <mask> argument of glXBlitContextFramebufferAMD: |
| |
| GL_COLOR_BUFFER_BIT |
| GL_DEPTH_BUFFER_BIT |
| GL_STENCIL_BUFFER_BIT |
| |
| Additions to the WGL Specification |
| |
| None. This specification is written for GLX. |
| |
| Additions to the GLX 1.4 Specification |
| |
| Add a new section in between 3.3.7 and 3.3.8 entitled "GPU |
| Associated Contexts" |
| |
| 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: |
| |
| unsigned int glXGetGPUIDsAMD(unsigned int maxCount, unsigned int *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 glXGetGPUIDsAMD 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 glXGetGPUIDsAMD |
| 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 glXGetGPUInfoAMD(unsigned int id, int property, GLenum dataType, |
| unsigned int size, void *data); |
| |
| <id> is a GPU id obtained from calling glXGetGPUIDsAMD. 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 glXGetGPUInfoAMD. |
| 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 |
| GLX_GPU_OPENGL_VERSION_STRING_AMD, GLX_GPU_RENDERER_STRING_AMD, |
| GLX_GPU_FASTEST_TARGET_GPUS_AMD, GLX_GPU_RAM_AMD, GLX_GPU_CLOCK_AMD, |
| GLX_GPU_NUM_PIPES_AMD, GLX_GPU_NUM_SIMD_AMD, GLX_GPU_NUM_RB_AMD, or |
| GLX_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 GLX_GPU_OPENGL_VERSION_STRING_AMD returns the highest supported |
| OpenGL version string and GLX_GPU_RENDERER_STRING_AMD returns name |
| of the GPU. <dataType> must be GL_UNSIGNED_BYTE with the previous |
| properties. Querying GLX_GPU_FASTEST_TARGET_GPUS_AMD returns an array |
| of the IDs of GPUs with the fastest data blit rates when using |
| glXBlitContextFramebufferAMD. 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 |
| GLX_GPU_RAM_AMD returns the amount of RAM available to GPU in MB. Querying |
| GLX_GPU_CLOCK_AMD returns the GPU clock speed in MHz. Querying |
| GLX_GPU_NUM_PIPES_AMD returns the nubmer of 3D pipes. Querying |
| GLX_GPU_NUM_SIMD_AMD returns the number of SIMD ALU units in each |
| shader pipe. Querying GLX_GPU_NUM_RB_AMD returns the number of render |
| backends. Querying GLX_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 glXCreateNewContext. |
| 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: |
| |
| unsigned int glXGetContextGPUIDAMD(GLXContext ctx); |
| |
| <ctx> is the context for which the GPU id will be returned. If the |
| context is invalid or if an error has occurred, glXGetContextGPUIDAMD |
| will return 0. |
| |
| To create an associated context, use: |
| |
| GLXContext glXCreateAssociatedContextAMD(unsigned int id, |
| GLXContext share_list); |
| |
| <id> must be a valid GPU id and cannot be 0. <share_list> must either |
| be NULL or that of an associated context created with the the same GPU |
| ID as <id>. If <share_list> was created using a different ID, |
| glXCreateAssociatedContextAMD will fail and return NULL. If a context was |
| successfully created the handle will be returned by |
| glXCreateAssociatedContextAMD. 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 and the context is not |
| tied to a specific Display. Associated contexts are always direct contexts. |
| Associated Contexts always support only GLX_RGBA_TYPE rendering type. |
| |
| glXCreateAssociatedContextAMD can generate the following errors: |
| GLXBadContext if <share_list> is neither zero nor a valid GLX rendering |
| context; BadMatch if the server context state for share list exists in |
| an address space that cannot be shared with the newly created context |
| or if share list was created on a different screen than the one |
| referenced by config; BadAlloc if the server does not have enough resources |
| to allocate the new context. |
| |
| To create an associated context and request a specific GL version, use: |
| |
| GLXContext glXCreateAssociatedContextAttribsAMD(unsigned int id, |
| GLXContext share_list, const int *attribList) |
| |
| All capabilities and limitations of glXCreateContextAttribsARB apply |
| to glXCreateAssociatedContextAttribsAMD. Additionally, <id> must be |
| a valid GPU ID and cannot be 0. If a context was successfully created |
| the handle will be returned by glXCreateAssociatedContextAttribsAMD. |
| If a context could not be created, NULL will be returned. Upon |
| successful creation, no pixel format is tied to an associated context. |
| |
| <share_list> must either be NULL or that of an associated context created |
| with the the same GPU ID as <id>. If <share_list> was created using a |
| different ID, glXCreateAssociatedContextAttribsAMD will fail and return NULL. |
| |
| glXCreateAssociatedContextAttribsAMD can generate the following errors: |
| GLXBadContext if <share_list> is neither zero nor a valid GLX rendering |
| context; BadMatch if the server context state for share list exists in |
| an address space that cannot be shared with the newly created context |
| or if share list was created on a different screen than the one |
| referenced by config; BadAlloc if the server does not have enough resources |
| to allocate the new context. |
| |
| A context must be deleted once it is no longer needed. Use the |
| following call to delete an associated context: |
| |
| Bool glXDeleteAssociatedContextAMD(GLXContext ctx); |
| |
| If the function succeeds, TRUE will be returned, otherwise FALSE is |
| returned. <ctx> must be a valid associated context created by |
| calling glXCreateAssociatedContextAMD. If an unassociated context, |
| created by calling glXCreateNewContext, is passed into <ctx>, the |
| function will fail. An associated context cannot be deleted by calling |
| glXDestroyContext. If an associated context is passed into |
| glXDestroyContext, the result is undefiend. |
| |
| To render using an associated context, it must be made the current |
| context for a thread: |
| |
| Bool glXMakeAssociatedContextCurrentAMD(GLXContext ctx); |
| |
| <ctx> is a context handle created by calling |
| glXCreateAssociatedContextAMD. If <ctx> was created using |
| glXCreateNewContext, the call will fail, FALSE will be returned and |
| the error BadAccess will be generated. If <ctx> is not a valid context |
| and not NULL, the call will fail, FALSE will be returned and the error |
| GLXBadContext will be generated. If the call succeeds, TRUE will be |
| returned. To detach the current associated context, pass NULL as <ctx>. |
| |
| Only one type of context can be current to a thread at a time. If an |
| unassociated context is current to a thread when |
| glXMakeAssociatedContextCurrentAMD is called with a valid <ctx>, it |
| is as if glxMakeContextCurrent is called first with a ctx value of NULL. |
| If an associated context is current and glxMakeContextCurrent is called |
| with a valid context, it is as if glXMakeAssociatedContextCurrentAMD is |
| called with a ctx value of NULL. |
| |
| The current associated context can be queried by calling: |
| |
| GLXContext glXGetCurrentAssociatedContextAMD(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. |
| |
| An associated context can not be passed in as a parameter into |
| glXCopyContext. If an associated context is passed into glXCopyContext, |
| the error GLXBadContext will be generated. |
| |
| The addresses returned from glXGetProcAddressARB 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 glXSwapBuffers when an associated context is current 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 glXBlitContextFramebufferAMD(GLXContext 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 glXBlitContextFramebufferAMD |
| is removed. |
| |
| Interactions with GL_EXT_framebuffer_object |
| |
| If GLX_AMD_gpu_association is supported, a context created with it |
| will also support EXT_framebuffer_object. |
| |
| |
| Interactions with GLX_SGI_make_current_read |
| |
| If the make current read extension is supported, it is invalid to pass |
| an associated context handle as a parameter to |
| glXMaketCurrentReadSGI. If an associated context is passed into |
| glXMaketCurrentReadSGI, the error GLXBadContext will be generated. |
| |
| Interactions with GLX_create_context |
| |
| If GLX_create_context is not supported, all language |
| referring to glXCreateAssociatedContextAttribsAMD is removed. |
| |
| |
| Issues |
| |
| 1) Should the language for the new context creation methods be added to |
| GLX 1.4 section 3.3.7 or in a new section? |
| |
| Resolved. Although it is also possible to add this exension text to |
| section 3.3.7, the resulting text would not flow well or be as coherent. |
| |
| |
| Revision History |
| |
| |
| Rev. Date Author Changes |
| ---- -------- -------- --------------------------------------------- |
| |
| 2 09/18/2014 gsellers Fixed types in function prototypes. |
| Update contact. Minor formatting fixes. |
| 0.1 11/04/2009 nickh Initial version. |
