Documentation of supported marker APIs/extensions would be great

[kg]

Description

In https://www.elopezr.com/a-macro-view-of-nanite/ I noticed the author's renderdoc screenshot contained some really cool annotations that I didn't realize renderdoc was even capable of capturing. I dug around in the documentation (in-application API, etc) and couldn't find any clues to how I would feed the relevant data through:

It would be great if the docs had a brief section listing which APIs/extensions are supported for the various backends so that an app developer can then read the docs for the relevant APIs/extensions and integrate them into their renderer. I could always go through and read UE5's direct3d renderer, I guess :-)

Environment

Not applicable

[baldurk]

These markers are available through API standard marker methods, which are documented in those particular APIs. I should support all available marker methods (some APIs have more variants than others but I think all of them have more than one).

There's also a section calling them out in RenderDoc's documentation.

FYI in future please fill out the environment section for all issues including feature requests, as it gives context that can be useful such as the OS and graphics API that you're using.

[kg]

Would you accept a PR to add a link or call-out for that section under "how do i" or "in application API"? I checked a bunch of places, so making it visible somewhere other than the event window docs could be good, and a "see here" hyperlink would do the trick

On June 1, 2021 1:43:04 AM PDT, Baldur Karlsson ***@***.***> wrote: Closed #2285. -- You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub: #2285 (comment)

- kg (mobile)

[baldurk]

I wouldn't want it to be listed/linked from the in-application API page, because that's describing RenderDoc 's API and I think it's important to keep a distinction there. Maybe it could be linked from a "how do I" page but I'm not sure which one you'd want to link it from? I'm not opposed to making changes but I just want to make sure links are only added where they make sense and there's sufficient value, to avoid adding lots of intra-links everywhere which I find makes it hard to navigate.

FYI it's the first result for searching "annotations" currently.

[kg]

I guess it's user error then, i only read that "how do i" entry and didn't use the search box. Thanks

On June 1, 2021 3:24:47 AM PDT, Baldur Karlsson ***@***.***> wrote: I wouldn't want it to be listed/linked from the in-application API page, because that's describing _RenderDoc_ 's API and I think it's important to keep a distinction there. Maybe it could be linked from a "how do I" page but I'm not sure which one you'd want to link it from? I'm not opposed to making changes but I just want to make sure links are only added where they make sense and there's sufficient value, to avoid adding lots of intra-links everywhere which I find makes it hard to navigate. FYI it's the first result for [searching "annotations"](https://renderdoc.org/docs/search.html?q=annotations&check_keywords=yes&area=default) currently. -- You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub: #2285 (comment)

- kg (mobile)

[baldurk]

Which "how do I" did you read? Those are intended to be sort of user stories/worked examples of high level tasks rather than feature reference, which is why my mind didn't go to them necessarily. Though in principle almost anything could fit that template.

I'll still look at this and see if it could be made clearer, but indeed I'm not sure yet that anything needs to change.

[kg]

Which "how do I" did you read? Those are intended to be sort of user stories/worked examples of high level tasks rather than feature reference, which is why my mind didn't go to them necessarily. Though in principle almost anything could fit that template.

I'll still look at this and see if it could be made clearer, but indeed I'm not sure yet that anything needs to change.

I read "How do I annotate a capture?", which you can see is result #2 in the search. I would have expected it to also mention the supported APIs (a hyperlink to the relevant page would be sufficient) since that's the other way to annotate a capture. Knowing about the search, it's not unreasonable to expect someone to use it, but I started by looking at the "how do I" and then figured that was all there was.

I'm already using glStringMarker and some of the D3DPERF APIs, so I figured I was perhaps expected to just figure it out (I knew vulkan had an API for this).

FWIW I omitted environment because I support all backends, so I need to know about all of them - not necessarily looking for platform-focused guidance or a 'here's how you do it' so much as just 'these are the extensions or APIs renderdoc supports', since some tracing tools only support a subset of them. I assume renderdoc supports most or all of them, though :-)

[baldurk]

Oh yeh now that I look at it with fresh eyes that is definitely ambiguous :/. It was supposed to be about the ways that you could annotate a capture after making it, which is why I didn't mention the markers an application can emit or the ways of setting resource names from your code. Annotation is kind of an overload term (overloaded terms in graphics? who'd have thought).

And yeh indeed if there's a marker method I don't support then that's a bug :). Since as much as possible I want things to Just Work:tm:. The reason I asked for the environment to always be listed in feature requests is because it's better to list it up front even if it doesn't end up being useful, rather than omitting it and then having to ask. It's totally fine to list multiple APIs or OSs for a case like this.

[baldurk]

That commit moves the capture-time annotation (marker regions and object names via graphics API calls) out of the other pages and into the "how do I annotate a capture" page so that it's all together. That was definitely a bit of an unintentional trap since I added the replay time annotation in much later, and didn't go back and adjust the other docs :/.