From 46644e127f5b478d04a5a699bddcbf6964083659 Mon Sep 17 00:00:00 2001 From: baldurk Date: Mon, 12 Sep 2016 15:09:13 +0200 Subject: [PATCH] Add some introductory text to the in-application API about how to start --- docs/in_application_api.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/in_application_api.rst b/docs/in_application_api.rst index cac80f0fe..ba3f0a436 100644 --- a/docs/in_application_api.rst +++ b/docs/in_application_api.rst @@ -3,12 +3,22 @@ In-application API Reference for RenderDoc in-application API version 1.1.1 +Make sure to use a matching API header for your build - if you use a newer header, the API version may not be available. All RenderDoc builds supporting this API ship the header in their root directory. + .. |semver_link| raw:: html semantic versioning This page describes the RenderDoc API exposed to applications being captured, both in overall organisation as well as a specific reference on each function. +To begin using the API you need to fetch the ``RENDERDOC_GetAPI`` function. You should do this dynamically, it is not recommended to actually link against RenderDoc's DLL as it's intended to be injected or loaded at runtime. The header does not declare ``RENDERDOC_GetAPI``, it declares a function pointer typedef ``pRENDERDOC_GetAPI`` that you can use. + +The two common ways to integrate RenderDoc are either to passively check if the DLL is loaded, and use the API. This lets you continue to use RenderDoc entirely as normal, launching your program through the UI, but you can access additional functionality to e.g. trigger captures at custom times. + +To do this you'll use your platforms dynamic library functions to see if the library is open already - e.g. ``GetModuleHandle`` on Windows, or ``dlopen`` with the ``RTLD_NOLOAD`` flag if available on \*nix systems. Just searching for the module name - ``renderdoc.dll`` or ``librenderdoc.so`` is sufficient here, so you don't need to know the path to where RenderDoc is running from. Then you can use ``GetProcAddress`` or ``dlsym`` to fetch the ``RENDERDOC_GetAPI`` function using the typedef above. + +The other way is a closer integration, where your code will explicitly load up RenderDoc. This needs more care taken as it can be a bit more complex. You will need to locate the RenderDoc module yourself, and load it as soon as possible after startup of your program. Due to the nature of RenderDoc's API hooking, the earlier you can load it the better in general. Once you've loaded it you can fetch the ``RENDERDOC_GetAPI`` entry point as above, and use the API as normal. + .. cpp:function:: int RENDERDOC_GetAPI(RENDERDOC_Version version, void **outAPIPointers)