Repository navigation
Proposal: Integration with debug tooling #121
Description
No matter what technologies we choose, we should make sure that our debugging story is top-notch. The far away lead contender for graphics debugging is RenderDoc, which I find to be the only tool I can consistently use to debug WebGL 2 issues. There is a lot of dimensions to debug tooling, especially with respect to shader debugging, but right now, I would like to simply propose a way to add markers so the user can identify draw calls and compute dispatches.
I propose two additions to WebGPUPassEncoder, and one to WebGPUDevice.
interface WebGPUPassEncoder {
void pushDebugGroup(DOMString groupName);
void popDebugGroup(DOMString groupName);
void insertDebugMarker(DOMString markerName);
}
interface WebGPUDevice {
void setResourceName(object o, DOMString resourceName);
}These trivially map to equivalents in every major API. Vulkan has VK_EXT_debug_marker, Metal has similar commands in MTLCommandEncoder, D3D12 has similar commands in ID3D12CommandQueue.
Resource names (sometimes called object labels) might be a bit goofy, because one API's concept of "resource" might not match another, especially for implicit states. For equivalent usage, Vulkan again has equivalents in VK_EXT_debug_marker, Metal has a label property on most resource objects, and D3D12 has ID3D12Object::SetObjectName.
Activity
Kangz commentedon Nov 16, 2018
+1, two comments:
DOMStringmagcius commentedon Nov 16, 2018
Quite possibly, however all APIs let you set the resource name after construction, and a lot of engines might call some internal
MakePlatformResource()and set the label after in higher-level user code. Weeding the string all the way through might be annoying for some.kvark commentedon Nov 20, 2018
Do we require
VK_EXT_debug_markerthen? Or do we specify that those instructions can be ignored by the implementation?Also, why
WebGPUDevice::setResourceNameas opposed toResource::setName? (frankly, I'd prefer the name to be in the descriptor like @Kangz suggested).magcius commentedon Nov 20, 2018
VK_EXT_debug_markerand such will be implemented by renderdoc hooks. If it doesn't exist, that means there isn't a debugger attached, so it is fine to ignore.Vulkan's vkDebugMarkerSetObjectName takes a device as the first arrgument. I imagine many resources would track their origin device already, but I put it on the device on the off-chance they don't.
magcius commentedon Nov 20, 2018
Also, I have definitely worked on two production shipping engines that use this pattern:
Requiring higher-level engines to move their settings to the descriptor create time might be tricky when all low-level platform APIs already support changing a resource name after construction.
kainino0x commentedon Nov 20, 2018
That sounds unfortunate, as it makes it hard to track errors inside CreateTexture - e.g. allocation failures, which a "dev layer" can catch synchronously with an exception with a stack trace, but in production will happen asynchronously before the name is known (that is, assuming that the "set name" is an ordered operation, and isn't allowed to "race" ahead of other operations).
It would seem ok to me if we had
namein the descriptor as well as anameproperty or setter on the object itself. I think implementations will always be able to get the device object easily.We'll want to use the name for other diagnostics (error messages) as well - not just native debugging support. For diagnostics, the name could be considered purely client-side, but native debugging means it needs to be propagated as an ordered operation.
magcius commentedon Nov 21, 2018
That sounds fine to me. For any case where developers are having trouble tracking allocation errors, they can add their own debug name to the descriptor.
kainino0x commentedon Nov 21, 2018
One more thing is we should do an investigation of this kind of thing in each of the backends. I don't know if they all allow arbitrary multiple renames on all objects, for example.
Thinking further, it would be slightly weird if setting a settable property enqueued an operation to the service side - but not that bad.
magcius commentedon Nov 21, 2018
My understanding is that names are not serialized -- the "last name" wins. This appears to at least be true with renderdoc's implementation: https://github.com/baldurk/renderdoc/blob/v1.x/renderdoc/driver/d3d12/d3d12_device.cpp#L2055-L2077
I don't believe there are any implementations of these debug layers outside of the tools (e.g. AMD OpenView, NVIDIA Nsight, PIX, Renderdoc, Xcode, etc.)
I have also worked with platforms that require you to allocate your own memory for the name -- if you use temporary memory it just appears as junk, which indeed makes it appear like the string isn't copied or even serialized, the debugger just stores a pointer.
magcius commentedon Nov 28, 2018
Seems like this was solved by #126. Closing.
Run tests serially in cmdline runner (gpuweb#121)