1Name 2 3 AMD_gpu_association 4 5Name Strings 6 7 GLX_AMD_gpu_association 8 9Contact 10 11 David Mao, AMD (david.mao 'at' amd.com) 12 13Status 14 15 Complete 16 17Version 18 19 Last Modified Date: September 18, 2014 20 Author Revision: 2 21 22 Based on: GLX_SGI_make_current_read specification 23 Date: 3/20/1997 24 25 EXT_framebuffer_object specification 26 Date: 2/13/2007 Revision #119 27 28Number 29 30 398 31 32Dependencies 33 34 OpenGL 1.5 is required. 35 36 GLX 1.3 is required. 37 38 GL_EXT_framebuffer_object is required. 39 40 GLX_ARB_get_proc_address is required. 41 42 This extension interacts with GLX_SGI_make_current_read. 43 44 This extension interacts with GL_EXT_framebuffer_blit. 45 46 This extension interacts with GLX_ARB_create_context. 47 48 This extension interacts with WGL_AMD_gpu_association. 49 50Overview 51 52 53 There currently is no way for applications to efficiently use GPU 54 resources in systems that contain more than one GPU. Vendors have 55 provided methods that attempt to split the workload for an 56 application among the available GPU resources. This has proven to be 57 very inefficient because most applications were never written with 58 these sorts of optimizations in mind. 59 60 This extension provides a mechanism for applications to explicitly 61 use the GPU resources on a given system individually. By providing 62 this functionality, a driver allows applications to make appropriate 63 decisions regarding where and when to distribute rendering tasks. 64 65 The set of GPUs available on a system can be queried by calling 66 glXGetGPUIDsAMD. The current GPU assigned to a specific context 67 can be determined by calling glXGetContextGPUIDAMD. Each GPU in a 68 system may have different performance characteristics in addition 69 to supporting a different version of OpenGL. The specifics of each 70 GPU can be obtained by calling glXGetGPUInfo. This will allow 71 applications to pick the most appropriate GPU for each rendering 72 task. 73 74 Once all necessary GPU information has been obtained, a context tied 75 to a specific GPU can be created with glXCreateAssociatedContextAMD. 76 These associated contexts can be made current with 77 glXMakeAssociatedContextCurrentAMD and deleted with 78 glXDeleteAssociatedContextAMD. Only one GPU associated or 79 non-associated context can be current at one time per thread. 80 81 To provide an accelerated path for blitting data from one context 82 to another, the new blit function BlitContextFramebufferAMD has 83 been added. 84 85 86 87 88New Procedures and Functions 89 90 unsigned int glXGetGPUIDsAMD(unsigned int maxCount, unsigned int *ids); 91 92 int glXGetGPUInfoAMD(unsigned int id, int property, GLenum dataType, 93 unsigned int size, void *data) 94 95 unsigned int glXGetContextGPUIDAMD(GLXContext ctx); 96 97 GLXContext glXCreateAssociatedContextAMD(unsigned int id, 98 GLXContext share_list); 99 100 GLXContext glXCreateAssociatedContextAttribsAMD(unsigned int id, 101 GLXContext share_context, 102 const int *attribList); 103 104 Bool glXDeleteAssociatedContextAMD(GLXContext ctx); 105 106 Bool glXMakeAssociatedContextCurrentAMD(GLXContext ctx); 107 108 GLXContext glXGetCurrentAssociatedContextAMD(void); 109 110 void glXBlitContextFramebufferAMD(GLXContext dstCtx, GLint srcX0, GLint srcY0, 111 GLint srcX1, GLint srcY1, GLint dstX0, 112 GLint dstY0, GLint dstX1, GLint dstY1, 113 GLbitfield mask, GLenum filter); 114 115New Tokens 116 117 Accepted by the <property> parameter of glXGetGPUInfo: 118 119 GLX_GPU_VENDOR_AMD 0x1F00 120 GLX_GPU_RENDERER_STRING_AMD 0x1F01 121 GLX_GPU_OPENGL_VERSION_STRING_AMD 0x1F02 122 GLX_GPU_FASTEST_TARGET_GPUS_AMD 0x21A2 123 GLX_GPU_RAM_AMD 0x21A3 124 GLX_GPU_CLOCK_AMD 0x21A4 125 GLX_GPU_NUM_PIPES_AMD 0x21A5 126 GLX_GPU_NUM_SIMD_AMD 0x21A6 127 GLX_GPU_NUM_RB_AMD 0x21A7 128 GLX_GPU_NUM_SPI_AMD 0x21A8 129 130 Accepted by the <dataType> argument of glXGetGPUInfoAMD: 131 132 GL_UNSIGNED_BYTE 133 GL_UNSIGNED_INT 134 GL_INT 135 GL_FLOAT 136 137 Accepted by the <mask> argument of glXBlitContextFramebufferAMD: 138 139 GL_COLOR_BUFFER_BIT 140 GL_DEPTH_BUFFER_BIT 141 GL_STENCIL_BUFFER_BIT 142 143Additions to the WGL Specification 144 145 None. This specification is written for GLX. 146 147Additions to the GLX 1.4 Specification 148 149 Add a new section in between 3.3.7 and 3.3.8 entitled "GPU 150 Associated Contexts" 151 152 GPU Associated Contexts 153 154 When multiple GPUs are present, a context can be created for 155 off-screen rendering that is associated with a specific GPU. 156 This will allow applications to achieve an app-specific 157 distributed GPU utilization. 158 159 The IDs for available GPUs can be queried with the command: 160 161 unsigned int glXGetGPUIDsAMD(unsigned int maxCount, unsigned int *ids); 162 163 where <maxCount> is the max number of IDs that can be returned and 164 <ids> is the array of returned IDs. If the function succeeds, 165 the return value is the number of total GPUs available. The 166 value 0 is returned if no GPUs are available or if the call has 167 failed. The array pointer <ids> passed into the function will be 168 populated by the smaller of maxCount or the total GPU count 169 available. The ID 0 is reserved and will not be retuned as a 170 valid GPU ID. If the array <ids> is NULL, the function will 171 only return the total number of GPUs. <ids> will be tightly packed 172 with no 0 values between valid ids. 173 174 Calling glXGetGPUIDsAMD once with <maxCount> set to zero returns 175 the total available GPU count which can be used to allocate an 176 appropriately sized id array before calling glXGetGPUIDsAMD 177 again to query the full set of supported GPUs. 178 179 Each GPU in a system may have different properties, performance 180 characteristics and different supported OpenGL versions. To 181 determine which GPU is best suited for a specific task the 182 following functions may be used: 183 184 int glXGetGPUInfoAMD(unsigned int id, int property, GLenum dataType, 185 unsigned int size, void *data); 186 187 <id> is a GPU id obtained from calling glXGetGPUIDsAMD. The GPU ID 188 must be a valid GPU ID. The function will fail if <id> is an invalid 189 GPU ID and -1 will be returned. <property> is the information being 190 queried. <dataType> may be GL_UNSIGNED_INT, GL_INT, GL_FLOAT, or 191 GL_UNSIGNED_BYTE and signals what data type is to be returned. <size> 192 signals the size of the data buffer passed into glXGetGPUInfoAMD. 193 This is the count of the array of type <dataType>. <data> is the 194 buffer which will be filled with the requested information. For a 195 string, <size> will be the number of characters allocated and will 196 include NULL termination. For arrays of type GL_UNSIGNED_INT, GL_INT, 197 and GL_FLOAT <size> will be the array depth. If the function 198 succeeds, the number of values written will be returned. If the number 199 of values written is equal to <size>, the query should be repeated with 200 a larger <data> buffer. Strings should be queried using the 201 GL_UNSIGNED_BYTE type, are UTF-8 encoded and will be NULL terminated. 202 If the function fails, -1 will be returned. 203 204 <property> defines the GPU property to be queried, and may be one of 205 GLX_GPU_OPENGL_VERSION_STRING_AMD, GLX_GPU_RENDERER_STRING_AMD, 206 GLX_GPU_FASTEST_TARGET_GPUS_AMD, GLX_GPU_RAM_AMD, GLX_GPU_CLOCK_AMD, 207 GLX_GPU_NUM_PIPES_AMD, GLX_GPU_NUM_SIMD_AMD, GLX_GPU_NUM_RB_AMD, or 208 GLX_GPU_NUM_SPI_AMD. 209 210 If <size> is not sufficient to hold the entire value for a particular 211 property, the number of values returned will equal <size>. If 212 <dataType> is inappropriate for <property>, for instance INT for a 213 property which is a string, the function will fail and -1 will be 214 returned. 215 216 Querying GLX_GPU_OPENGL_VERSION_STRING_AMD returns the highest supported 217 OpenGL version string and GLX_GPU_RENDERER_STRING_AMD returns name 218 of the GPU. <dataType> must be GL_UNSIGNED_BYTE with the previous 219 properties. Querying GLX_GPU_FASTEST_TARGET_GPUS_AMD returns an array 220 of the IDs of GPUs with the fastest data blit rates when using 221 glXBlitContextFramebufferAMD. This list is ordered fastest 222 first. This provides a performance hint about which contexts and GPUS 223 are capable of transfering data between each other the quickest. Querying 224 GLX_GPU_RAM_AMD returns the amount of RAM available to GPU in MB. Querying 225 GLX_GPU_CLOCK_AMD returns the GPU clock speed in MHz. Querying 226 GLX_GPU_NUM_PIPES_AMD returns the nubmer of 3D pipes. Querying 227 GLX_GPU_NUM_SIMD_AMD returns the number of SIMD ALU units in each 228 shader pipe. Querying GLX_GPU_NUM_RB_AMD returns the number of render 229 backends. Querying GLX_GPU_NUM_SPI_AMD returns the number of shader 230 parameter interpolaters. If the <parameter> being queried is not 231 applicable for the GPU specified by <id>, the value 0 will be returned. 232 233 Unassociated contexts are created by calling glXCreateNewContext. 234 Although these contexts are unassociated, their use will still be 235 tied to a single GPU in most cases. For this reason it is advantageous 236 to be able to query the GPU an existing unassociated context resides 237 on. If multiple GPUs are available, it would be undesirable 238 to use one for rendering to visible surfaces and then chose the 239 same one for off-screen rendering. Use the following command to 240 determine which GPU a context is attached to: 241 242 unsigned int glXGetContextGPUIDAMD(GLXContext ctx); 243 244 <ctx> is the context for which the GPU id will be returned. If the 245 context is invalid or if an error has occurred, glXGetContextGPUIDAMD 246 will return 0. 247 248 To create an associated context, use: 249 250 GLXContext glXCreateAssociatedContextAMD(unsigned int id, 251 GLXContext share_list); 252 253 <id> must be a valid GPU id and cannot be 0. <share_list> must either 254 be NULL or that of an associated context created with the the same GPU 255 ID as <id>. If <share_list> was created using a different ID, 256 glXCreateAssociatedContextAMD will fail and return NULL. If a context was 257 successfully created the handle will be returned by 258 glXCreateAssociatedContextAMD. If a context could not be created, NULL 259 will be returned. If a context could not be created, error information 260 can be obtained by calling GetLastError. Upon successful creation, 261 no pixel format is tied to an associated context and the context is not 262 tied to a specific Display. Associated contexts are always direct contexts. 263 Associated Contexts always support only GLX_RGBA_TYPE rendering type. 264 265 glXCreateAssociatedContextAMD can generate the following errors: 266 GLXBadContext if <share_list> is neither zero nor a valid GLX rendering 267 context; BadMatch if the server context state for share list exists in 268 an address space that cannot be shared with the newly created context 269 or if share list was created on a different screen than the one 270 referenced by config; BadAlloc if the server does not have enough resources 271 to allocate the new context. 272 273 To create an associated context and request a specific GL version, use: 274 275 GLXContext glXCreateAssociatedContextAttribsAMD(unsigned int id, 276 GLXContext share_list, const int *attribList) 277 278 All capabilities and limitations of glXCreateContextAttribsARB apply 279 to glXCreateAssociatedContextAttribsAMD. Additionally, <id> must be 280 a valid GPU ID and cannot be 0. If a context was successfully created 281 the handle will be returned by glXCreateAssociatedContextAttribsAMD. 282 If a context could not be created, NULL will be returned. Upon 283 successful creation, no pixel format is tied to an associated context. 284 285 <share_list> must either be NULL or that of an associated context created 286 with the the same GPU ID as <id>. If <share_list> was created using a 287 different ID, glXCreateAssociatedContextAttribsAMD will fail and return NULL. 288 289 glXCreateAssociatedContextAttribsAMD can generate the following errors: 290 GLXBadContext if <share_list> is neither zero nor a valid GLX rendering 291 context; BadMatch if the server context state for share list exists in 292 an address space that cannot be shared with the newly created context 293 or if share list was created on a different screen than the one 294 referenced by config; BadAlloc if the server does not have enough resources 295 to allocate the new context. 296 297 A context must be deleted once it is no longer needed. Use the 298 following call to delete an associated context: 299 300 Bool glXDeleteAssociatedContextAMD(GLXContext ctx); 301 302 If the function succeeds, TRUE will be returned, otherwise FALSE is 303 returned. <ctx> must be a valid associated context created by 304 calling glXCreateAssociatedContextAMD. If an unassociated context, 305 created by calling glXCreateNewContext, is passed into <ctx>, the 306 function will fail. An associated context cannot be deleted by calling 307 glXDestroyContext. If an associated context is passed into 308 glXDestroyContext, the result is undefiend. 309 310 To render using an associated context, it must be made the current 311 context for a thread: 312 313 Bool glXMakeAssociatedContextCurrentAMD(GLXContext ctx); 314 315 <ctx> is a context handle created by calling 316 glXCreateAssociatedContextAMD. If <ctx> was created using 317 glXCreateNewContext, the call will fail, FALSE will be returned and 318 the error BadAccess will be generated. If <ctx> is not a valid context 319 and not NULL, the call will fail, FALSE will be returned and the error 320 GLXBadContext will be generated. If the call succeeds, TRUE will be 321 returned. To detach the current associated context, pass NULL as <ctx>. 322 323 Only one type of context can be current to a thread at a time. If an 324 unassociated context is current to a thread when 325 glXMakeAssociatedContextCurrentAMD is called with a valid <ctx>, it 326 is as if glxMakeContextCurrent is called first with a ctx value of NULL. 327 If an associated context is current and glxMakeContextCurrent is called 328 with a valid context, it is as if glXMakeAssociatedContextCurrentAMD is 329 called with a ctx value of NULL. 330 331 The current associated context can be queried by calling: 332 333 GLXContext glXGetCurrentAssociatedContextAMD(void); 334 335 The current associated context is returned on a successful call to 336 this function. If no associated context is current, NULL is returned. 337 If an unassociated context is current, NULL will be returned. 338 339 An associated context can not be passed in as a parameter into 340 glXCopyContext. If an associated context is passed into glXCopyContext, 341 the error GLXBadContext will be generated. 342 343 The addresses returned from glXGetProcAddressARB are only valid for the 344 current context. It may be invalid to use proc addresses obtained from 345 a traditional context with an associated context. Furthermore, the 346 OpenGL version and extensions supported on an associated context may 347 differ. Each context should be treated seperately, proc addressses 348 should be queried for each after context creation. 349 350 Calls to glXSwapBuffers when an associated context is current will have 351 no effect. 352 353 There is no way to use pBuffers with associated contexts. 354 355 Overlays and underlays are not supported with associated contexts. 356 357 The same associated context is used for both write and read operations. 358 359 To facilitate high performance data communication between multiple 360 contexts, a new function is necessary to blit data from one context 361 to another. 362 363 VOID glXBlitContextFramebufferAMD(GLXContext dstCtx, GLint srcX0, GLint srcY0, 364 GLint srcX1, GLint srcY1, GLint dstX0, 365 GLint dstY0, GLint dstX1, GLint dstY1, 366 GLbitfield mask, GLenum filter); 367 368 <dstCtx> is the context handle for the write context. <mask> is the 369 bitwise OR of a number of values indicating which buffers are to be 370 copied. The values are GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT, and 371 GL_STENCIL_BUFFER_BIT, which are described in section 4.2.3. The 372 pixels corresponding to these buffers are copied from the source 373 rectangle, bound by the locations (srcX0, srcY0) and (srcX1, srcY1), 374 to the destination rectangle, bound by the locations (dstX0, dstY0) 375 and (dstX1, dstY1). The lower bounds of the rectangle are inclusive, 376 while the upper bounds are exclusive. 377 378 The source context is the current GL context. Specifying the current 379 GL context as the <dstCtx> will result in the error 380 GL_INVALID_OPERATION being generated. If <dstCtx> is invalid, the 381 error GL_INVALID_OPERATION will be generated. If no context is 382 current at the time of this call, the error GL_INVALID_OPERATION 383 will be generated. These errors may be queried by calling glGetError. 384 The target framebuffer will be the framebuffer bound to 385 GL_DRAW_FRAMEBUFFER_EXT in the context <dstCtx>. The source framebuffer 386 will be the framebuffer bound to GL_READ_FRAMEBUFFER_EXT in the 387 currently bound context. 388 389 The restrictions that apply to the source and destination rectangles 390 specified with <srcX0>, <srcY0>, <srcX1>, <srcY1>, <dstX0>, <dstY0> 391 <dstX0>, and <dstY0> are the same as those that apply for 392 glBlitFramebufferEXT. The same error conditions exist as for 393 glBlitFramebufferEXT. 394 395 When called, this function will execute immediately in the currently 396 bound context. It is up to the caller to maintain appropriate 397 synchronization between the current context and <dstCtx> to ensure 398 rendering to the appropriate surfaces has completed on the current 399 and <dstCtx> contexts. 400 401Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment 402Operations and the Frame Buffer) 403Modify the beginning of section 4.4.1 as follows: 404 405 When an assoicated context is bound, the default state for an associated 406 context is invalid for rendering. Because there is no attached window, 407 there is no default framebuffer surface to render to. An app created 408 framebuffer object must be bound for rendering to be valid. If the 409 object bound to GL_FRAMEBUFFER_BINDING_EXT is 0, it is as if the 410 framebuffer is incomplete, and an 411 GL_INVALID_FRAMEBUFFER_OPERATION_EXT error will be generated 412 where rendering is attempted. 413 414 415New State 416 417 None 418 419 420Interactions with GL_EXT_framebuffer_blit 421 422 If the framebuffer blit extension is not supported, all language 423 referring to glBlitFramebufferEXT and glXBlitContextFramebufferAMD 424 is removed. 425 426Interactions with GL_EXT_framebuffer_object 427 428 If GLX_AMD_gpu_association is supported, a context created with it 429 will also support EXT_framebuffer_object. 430 431 432Interactions with GLX_SGI_make_current_read 433 434 If the make current read extension is supported, it is invalid to pass 435 an associated context handle as a parameter to 436 glXMaketCurrentReadSGI. If an associated context is passed into 437 glXMaketCurrentReadSGI, the error GLXBadContext will be generated. 438 439Interactions with GLX_create_context 440 441 If GLX_create_context is not supported, all language 442 referring to glXCreateAssociatedContextAttribsAMD is removed. 443 444 445Issues 446 447 1) Should the language for the new context creation methods be added to 448 GLX 1.4 section 3.3.7 or in a new section? 449 450 Resolved. Although it is also possible to add this exension text to 451 section 3.3.7, the resulting text would not flow well or be as coherent. 452 453 454Revision History 455 456 457 Rev. Date Author Changes 458 ---- -------- -------- --------------------------------------------- 459 460 2 09/18/2014 gsellers Fixed types in function prototypes. 461 Update contact. Minor formatting fixes. 462 0.1 11/04/2009 nickh Initial version. 463