GPU: Expose debug information from devices #12706
Conversation
There was a problem hiding this comment.
Broadly this looks okay to me, will defer to @thatcosmonaut and @TheSpydog for any insights involving D3D12 and Metal specifically.
|
Looks good to me, thanks! |
| * | ||
| * \since This function is available since SDL 3.4.0. | ||
| */ | ||
| extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGPUDeviceDebugProperties( |
There was a problem hiding this comment.
This should be changed to SDL_GetGPUDeviceProperties(), so we can extend it with non-debug properties in the future.
There was a problem hiding this comment.
I deliberately wanted to restrict this function to debug information to help avoid misuse of the contained data. Mixing debug and non-debug information would make the debug information appear more official and trustworthy than what it actually is.
I see no need to add non-debug information to this function as such information would be better exposed as individual new functions for each piece of data to make it easier to use from the app developer perspective.
| { | ||
| CHECK_DEVICE_MAGIC(device, 0); | ||
|
|
||
| return device->GetDeviceDebugProperties(device); |
There was a problem hiding this comment.
We shouldn't have a separate function to get these, they should instead be a props member of SDL_GPUDevice that's allocated at creation time, similar to SDL_Renderer.
There was a problem hiding this comment.
I originally tried that but due to how device creation is done it would require a much larger change set to avoid code duplication in each backend. The device object is only created at the very end of the function so the property group object will need to be separately tracked throughout the create function and manually cleaned up on every failure return path.
Co-authored-by: Nikita Kogut <glinka1202@gmail.com>
|
Merged, thanks! |
Supersedes: #12579
Fixes: #12489
This PR exposes debug information about GPU devices by providing a new API called SDL_GetGPUDeviceDebugProperties() that returns a property group that contains all the debug information that is already logged internally by the various GPU backends. This PR also provides a new input property to SDL_CreateGPUDeviceWithProperties() that can optionally disable the internal logging just in case the app wishes to do their own logging using the now-exposed debug information. By default the existing behavior is kept.
Exposing this information is useful for apps that wish to display the debug information to the user within the app's UI, or for forwarding the information to an external server for telemetric purposes.
This implementation interweaves population of the property group with the internal logging to reduce the amount of duplicate code and it provides more extensive documentation. All properties are optional and have very lenient formatting requirements to make it easier to maintain on SDL's side.
This PR maintains the existing coding style of the surrounding code even if the GPU code doesn't correctly follow SDL's coding style. This affects the new public property name SDL_PROP_GPU_DEVICE_CREATE_LOGDEBUGPROPS_BOOLEAN. For the properties of the new function I've opted to follow SDL's normal coding style instead of the existing GPU property names.
The documentation of the new function has complex formatting requirements and I was unable to figure out how to make it look nice with Markdown so it's instead just placed in a multiline code block for now.