AvaloniaUI
/
angle
зеркало из https://github.com/AvaloniaUI/angle.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Tests: Add support for --renderdoc 

This change adds support for a new flag namely `--renderdoc` to end2end
and deqp tests.  With this flag, each test automatically starts and ends
a frame capture in renderdoc, working around an issue where renderdoc
refuses to capture a test frame that doesn't start or end with a swap.

With end2end tests, the capture starts before test set up, and ends
after test tear down.  With deqp tests, it starts before init, ends and
restarts after each test iteration and ends after deinit.

Bug: angleproject:6072
Change-Id: Ib41b816aff121bf922d9147044cc363c33a62181
Reviewed-on: https://chromium-review.googlesource.com/c/angle/angle/+/2971835
Commit-Queue: Shahbaz Youssefi <syoussefi@chromium.org>
Reviewed-by: Cody Northrop <cnorthrop@google.com>
Reviewed-by: Jamie Madill <jmadill@chromium.org>
This commit is contained in:
Shahbaz Youssefi 2021-06-20 00:05:28 -04:00 коммит произвёл Angle LUCI CQ
Родитель 9412ac9c7c
Коммит 7df7fc7ff8
17 изменённых файлов: 905 добавлений и 11 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

6
src/common/system_utils.h
Просмотреть файл

@ -70,8 +70,12 @@ class Library : angle::NonCopyable
// (e.g. opengl32.dll)
enum class SearchType
{
// Try to find the library in the application directory
ApplicationDir,
SystemDir
// Load the library from the system directories
SystemDir,
// Get a reference to an already loaded shared library.
AlreadyLoaded,
};
Library *OpenSharedLibrary(const char *libraryName, SearchType searchType);

14
src/common/system_utils_posix.cpp
Просмотреть файл

@ -78,7 +78,9 @@ std::string GetModuleDirectory()
class PosixLibrary : public Library
{
public:
PosixLibrary(const std::string &fullPath) : mModule(dlopen(fullPath.c_str(), RTLD_NOW)) {}
PosixLibrary(const std::string &fullPath, int extraFlags)
: mModule(dlopen(fullPath.c_str(), RTLD_NOW | extraFlags))
{}
~PosixLibrary() override
{
@ -117,17 +119,23 @@ Library *OpenSharedLibrary(const char *libraryName, SearchType searchType)
#endif
}
int extraFlags = 0;
if (searchType == SearchType::AlreadyLoaded)
{
extraFlags = RTLD_NOLOAD;
}
std::string fullPath = directory + libraryName + "." + GetSharedLibraryExtension();
#if ANGLE_PLATFORM_IOS
// On iOS, dlopen needs a suffix on the framework name to work.
fullPath = fullPath + "/" + libraryName;
#endif
return new PosixLibrary(fullPath);
return new PosixLibrary(fullPath, extraFlags);
}
Library *OpenSharedLibraryWithExtension(const char *libraryName)
{
return new PosixLibrary(libraryName);
return new PosixLibrary(libraryName, 0);
}
bool IsDirectory(const char *filename)

3
src/common/system_utils_win32.cpp
Просмотреть файл

@ -50,6 +50,9 @@ class Win32Library : public Library
case SearchType::SystemDir:
mModule = LoadLibraryExA(libraryName, nullptr, LOAD_LIBRARY_SEARCH_SYSTEM32);
break;
case SearchType::AlreadyLoaded:
mModule = GetModuleHandleA(libraryName);
break;
}
}

1
src/common/system_utils_winuwp.cpp
Просмотреть файл

@ -44,6 +44,7 @@ class UwpLibrary : public Library
mModule = LoadPackagedLibrary(wideBuffer.c_str(), 0);
break;
case SearchType::SystemDir:
case SearchType::AlreadyLoaded:
// Not supported in UWP
break;
}

3
src/tests/BUILD.gn
Просмотреть файл

@ -104,6 +104,9 @@ template("angle_common_test_utils") {
"//third_party/googletest:gtest",
]
sources = [
"$angle_root/third_party/renderdoc/src/renderdoc_app.h",
"test_utils/RenderDoc.cpp",
"test_utils/RenderDoc.h",
"test_utils/angle_test_configs.cpp",
"test_utils/angle_test_configs.h",
"test_utils/angle_test_instantiate.cpp",

10
src/tests/deqp_support/angle_deqp_gtest.cpp
Просмотреть файл

@ -116,6 +116,7 @@ constexpr char kANGLEEGLString[] = "--use-angle=";
constexpr char kANGLEPreRotation[] = "--emulated-pre-rotation=";
constexpr char kdEQPCaseString[] = "--deqp-case=";
constexpr char kVerboseString[] = "--verbose";
constexpr char kRenderDocString[] = "--renderdoc";
std::array<char, 500> gCaseStringBuffer;
@ -133,6 +134,8 @@ constexpr uint32_t kDefaultPreRotation = 0;
const APIInfo *gInitAPI = nullptr;
uint32_t gPreRotation = kDefaultPreRotation;
bool gEnableRenderDocCapture = false;
constexpr const char gdEQPEGLConfigNameString[] = "--deqp-gl-config-name=";
constexpr const char gdEQPLogImagesString[] = "--deqp-log-images=";
@ -555,7 +558,8 @@ void dEQPTest<TestModuleIndex>::SetUpTestCase()
// Init the platform.
if (!deqp_libtester_init_platform(static_cast<int>(argv.size()), argv.data(),
reinterpret_cast<void *>(&HandlePlatformError), gPreRotation))
reinterpret_cast<void *>(&HandlePlatformError), gPreRotation,
gEnableRenderDocCapture))
{
std::cout << "Aborting test due to dEQP initialization error." << std::endl;
exit(1);
@ -758,6 +762,10 @@ void InitTestHarness(int *argc, char **argv)
{
HandleLogImages(argv[argIndex] + strlen(gdEQPLogImagesString));
}
else if (strncmp(argv[argIndex], kRenderDocString, strlen(kRenderDocString)) == 0)
{
gEnableRenderDocCapture = true;
}
argIndex++;
}

3
src/tests/deqp_support/angle_deqp_libtester.h
Просмотреть файл

@ -42,7 +42,8 @@ ANGLE_LIBTESTER_EXPORT int deqp_libtester_main(int argc, const char *argv[]);
ANGLE_LIBTESTER_EXPORT bool deqp_libtester_init_platform(int argc,
const char *argv[],
void *logErrorFunc,
uint32_t preRotation);
uint32_t preRotation,
bool enableRenderDocCapture);
ANGLE_LIBTESTER_EXPORT void deqp_libtester_shutdown_platform();
ANGLE_LIBTESTER_EXPORT dEQPTestResult deqp_libtester_run(const char *caseName);

7
src/tests/deqp_support/angle_deqp_libtester_main.cpp
Просмотреть файл

@ -51,7 +51,8 @@ std::string GetLogFileName(std::string deqpDataDir)
ANGLE_LIBTESTER_EXPORT bool deqp_libtester_init_platform(int argc,
const char *argv[],
void *logErrorFunc,
uint32_t preRotation)
uint32_t preRotation,
bool enableRenderDocCapture)
{
try
{
@ -81,7 +82,7 @@ ANGLE_LIBTESTER_EXPORT bool deqp_libtester_init_platform(int argc,
g_log = new tcu::TestLog(GetLogFileName(deqpDataDir).c_str(), g_cmdLine->getLogFlags());
g_testCtx = new tcu::TestContext(*g_platform, *g_archive, *g_log, *g_cmdLine, DE_NULL);
g_root = new tcu::TestPackageRoot(*g_testCtx, tcu::TestPackageRegistry::getSingleton());
g_executor = new tcu::RandomOrderExecutor(*g_root, *g_testCtx);
g_executor = new tcu::RandomOrderExecutor(*g_root, *g_testCtx, enableRenderDocCapture);
}
catch (const std::exception &e)
{
@ -95,7 +96,7 @@ ANGLE_LIBTESTER_EXPORT bool deqp_libtester_init_platform(int argc,
// Exported to the tester app.
ANGLE_LIBTESTER_EXPORT int deqp_libtester_main(int argc, const char *argv[])
{
if (!deqp_libtester_init_platform(argc, argv, nullptr, 0))
if (!deqp_libtester_init_platform(argc, argv, nullptr, 0, false))
{
tcu::die("Could not initialize the dEQP platform");
}

3
src/tests/deqp_support/deqp.gni
Просмотреть файл

@ -2021,6 +2021,9 @@ deqp_libtester_sources = [
"deqp_support/tcuANGLENativeDisplayFactory.h",
# TODO(jmadill): integrate with dEQP
"$angle_root/third_party/renderdoc/src/renderdoc_app.h",
"deqp_support/tcuRandomOrderExecutor.cpp",
"deqp_support/tcuRandomOrderExecutor.h",
"test_utils/RenderDoc.cpp",
"test_utils/RenderDoc.h",
]

22
src/tests/deqp_support/tcuRandomOrderExecutor.cpp
Просмотреть файл

@ -38,11 +38,18 @@ using std::vector;
namespace tcu
{
RandomOrderExecutor::RandomOrderExecutor(TestPackageRoot &root, TestContext &testCtx)
RandomOrderExecutor::RandomOrderExecutor(TestPackageRoot &root,
TestContext &testCtx,
bool enableRenderDocCapture)
: m_testCtx(testCtx), m_inflater(testCtx)
{
m_nodeStack.push_back(NodeStackEntry(&root));
root.getChildren(m_nodeStack[0].children);
if (enableRenderDocCapture)
{
mRenderDoc.attach();
}
}
RandomOrderExecutor::~RandomOrderExecutor(void)
@ -196,6 +203,7 @@ tcu::TestStatus RandomOrderExecutor::executeInner(TestCase *testCase, const std:
// Initialize, will return immediately if fails
try
{
mRenderDoc.startFrame();
m_caseExecutor->init(testCase, casePath);
}
catch (const std::bad_alloc &)
@ -217,6 +225,8 @@ tcu::TestStatus RandomOrderExecutor::executeInner(TestCase *testCase, const std:
return TestStatus(QP_TEST_RESULT_FAIL, e.getMessage());
}
bool isFirstFrameBeingCaptured = true;
// Execute
for (;;)
{
@ -226,6 +236,15 @@ tcu::TestStatus RandomOrderExecutor::executeInner(TestCase *testCase, const std:
try
{
// Make every iteration produce one renderdoc frame. Include the init code in the first
// frame, and the deinit code in the last frame.
if (!isFirstFrameBeingCaptured)
{
mRenderDoc.endFrame();
mRenderDoc.startFrame();
}
isFirstFrameBeingCaptured = false;
iterateResult = m_caseExecutor->iterate(testCase);
}
catch (const std::bad_alloc &)
@ -259,6 +278,7 @@ tcu::TestStatus RandomOrderExecutor::executeInner(TestCase *testCase, const std:
try
{
m_caseExecutor->deinit(testCase);
mRenderDoc.endFrame();
}
catch (const tcu::Exception &e)
{

6
src/tests/deqp_support/tcuRandomOrderExecutor.h
Просмотреть файл

@ -27,13 +27,15 @@
#include "deUniquePtr.hpp"
#include "tcuTestHierarchyIterator.hpp"
#include "tests/test_utils/RenderDoc.h"
namespace tcu
{
class RandomOrderExecutor
{
public:
RandomOrderExecutor(TestPackageRoot &root, TestContext &testCtx);
RandomOrderExecutor(TestPackageRoot &root, TestContext &testCtx, bool enableRenderDocCapture);
~RandomOrderExecutor(void);
TestStatus execute(const std::string &path);
@ -59,6 +61,8 @@ class RandomOrderExecutor
std::vector<NodeStackEntry> m_nodeStack;
de::MovePtr<TestCaseExecutor> m_caseExecutor;
RenderDoc mRenderDoc;
};
} // namespace tcu

17
src/tests/test_utils/ANGLETest.cpp
Просмотреть файл

@ -354,6 +354,7 @@ constexpr char kReuseDisplays[] = "--reuse-displays";
constexpr char kEnableANGLEPerTestCaptureLabel[] = "--angle-per-test-capture-label";
constexpr char kBatchId[] = "--batch-id=";
constexpr char kDelayTestStart[] = "--delay-test-start=";
constexpr char kRenderDoc[] = "--renderdoc";
void SetupEnvironmentVarsForCaptureReplay()
{
@ -378,6 +379,8 @@ void SetTestStartDelay(const char *testStartDelay)
gTestStartDelaySeconds = std::stoi(testStartDelay);
}
bool gEnableRenderDocCapture = false;
// static
std::array<Vector3, 6> ANGLETestBase::GetQuadVertices()
{
@ -425,6 +428,11 @@ ANGLETestBase::ANGLETestBase(const PlatformParameters &params)
#endif
}
if (gEnableRenderDocCapture)
{
mRenderDoc.attach();
}
auto iter = gFixtures.find(withMethods);
if (iter != gFixtures.end())
{
@ -684,6 +692,8 @@ void ANGLETestBase::ANGLETestSetUp()
glViewport(0, 0, mWidth, mHeight);
mIsSetUp = true;
mRenderDoc.startFrame();
}
void ANGLETestBase::ANGLETestTearDown()
@ -699,12 +709,15 @@ void ANGLETestBase::ANGLETestTearDown()
if (mCurrentParams->noFixture || !mFixture->osWindow->valid())
{
mRenderDoc.endFrame();
return;
}
swapBuffers();
mFixture->osWindow->messageLoop();
mRenderDoc.endFrame();
if (mFixture->eglWindow)
{
checkD3D11SDKLayersMessages();
@ -1522,5 +1535,9 @@ void ANGLEProcessTestArgs(int *argc, char *argv[])
{
SetTestStartDelay(argv[argIndex] + strlen(kDelayTestStart));
}
else if (strncmp(argv[argIndex], kRenderDoc, strlen(kRenderDoc)) == 0)
{
gEnableRenderDocCapture = true;
}
}
}

3
src/tests/test_utils/ANGLETest.h
Просмотреть файл

@ -14,6 +14,7 @@
#include <algorithm>
#include <array>
#include "RenderDoc.h"
#include "angle_test_configs.h"
#include "angle_test_platform.h"
#include "common/angleutils.h"
@ -584,6 +585,8 @@ class ANGLETestBase
const angle::PlatformParameters *mCurrentParams;
TestFixture *mFixture;
RenderDoc mRenderDoc;
// Workaround for NVIDIA not being able to share a window with OpenGL and Vulkan.
static Optional<EGLint> mLastRendererType;
static Optional<angle::GLESDriverType> mLastLoadedDriver;

85
src/tests/test_utils/RenderDoc.cpp Normal file
Просмотреть файл

@ -0,0 +1,85 @@
//
// Copyright 2021 The ANGLE Project Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// RenderDoc:
// Connection to renderdoc for capturing tests through its API.
//
#include "RenderDoc.h"
#include "common/angleutils.h"
#include "common/debug.h"
RenderDoc::RenderDoc() : mRenderDocModule(nullptr), mApi(nullptr) {}
RenderDoc::~RenderDoc()
{
SafeDelete(mRenderDocModule);
}
#if defined(ANGLE_PLATFORM_ANDROID) || defined(ANGLE_PLATFORM_LINUX) || \
defined(ANGLE_PLATFORM_WINDOWS)
# include "third_party/renderdoc/src/renderdoc_app.h"
# if defined(ANGLE_PLATFORM_WINDOWS)
constexpr char kRenderDocModuleName[] = "renderdoc";
# elif defined(ANGLE_PLATFORM_ANDROID)
constexpr char kRenderDocModuleName[] = "libVkLayer_GLES_RenderDoc";
# else
constexpr char kRenderDocModuleName[] = "librenderdoc";
# endif
void RenderDoc::attach()
{
mRenderDocModule = OpenSharedLibrary(kRenderDocModuleName, angle::SearchType::AlreadyLoaded);
if (mRenderDocModule == nullptr || mRenderDocModule->getNative() == nullptr)
{
return;
}
void *getApi = mRenderDocModule->getSymbol("RENDERDOC_GetAPI");
if (getApi == nullptr)
{
return;
}
int result = reinterpret_cast<pRENDERDOC_GetAPI>(getApi)(eRENDERDOC_API_Version_1_1_2, &mApi);
if (result != 1)
{
ERR() << "RenderDoc module is present but API 1.1.2 is unavailable";
mApi = nullptr;
}
}
void RenderDoc::startFrame()
{
if (mApi)
{
static_cast<RENDERDOC_API_1_1_2 *>(mApi)->StartFrameCapture(nullptr, nullptr);
}
}
void RenderDoc::endFrame()
{
if (mApi)
{
static_cast<RENDERDOC_API_1_1_2 *>(mApi)->EndFrameCapture(nullptr, nullptr);
}
}
#else // defiend(ANGLE_PLATFORM_ANDROID) || defined(ANGLE_PLATFORM_LINUX) ||
// defined(ANGLE_PLATFORM_WINDOWS)
// Stub out the implementation on unsupported platforms.
void RenderDoc::attach()
{
mApi = nullptr;
}
void RenderDoc::startFrame() {}
void RenderDoc::endFrame() {}
#endif // defiend(ANGLE_PLATFORM_ANDROID) || defined(ANGLE_PLATFORM_LINUX) ||
// defined(ANGLE_PLATFORM_WINDOWS)

30
src/tests/test_utils/RenderDoc.h Normal file
Просмотреть файл

@ -0,0 +1,30 @@
//
// Copyright 2021 The ANGLE Project Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// RenderDoc:
// Connection to renderdoc for capturing tests through its API.
//
#ifndef TESTS_TEST_UTILS_RENDERDOC_H_
#define TESTS_TEST_UTILS_RENDERDOC_H_
#include "common/system_utils.h"
class RenderDoc
{
public:
RenderDoc();
~RenderDoc();
void attach();
void startFrame();
void endFrame();
private:
angle::Library *mRenderDocModule;
void *mApi;
};
#endif // TESTS_TEST_UTILS_RENDERDOC_H_

11
third_party/renderdoc/README.chromium поставляемый Normal file
Просмотреть файл

@ -0,0 +1,11 @@
Name: RenderDoc API Header
URL: https://raw.githubusercontent.com/baldurk/renderdoc/v1.1/renderdoc/api/app/renderdoc_app.h
License: MIT
License File: NOT_SHIPPED
Security Critical: no
Description:
Header file for RenderDoc's in-app capture API.
Local modifications:
None

692
third_party/renderdoc/src/renderdoc_app.h поставляемый Normal file
Просмотреть файл

@ -0,0 +1,692 @@
/******************************************************************************
* The MIT License (MIT)
*
* Copyright (c) 2015-2018 Baldur Karlsson
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
******************************************************************************/
#pragma once
//////////////////////////////////////////////////////////////////////////////////////////////////
//
// Documentation for the API is available at https://renderdoc.org/docs/in_application_api.html
//
#if !defined(RENDERDOC_NO_STDINT)
# include <stdint.h>
#endif
#if defined(WIN32)
# define RENDERDOC_CC __cdecl
#elif defined(__linux__)
# define RENDERDOC_CC
#elif defined(__APPLE__)
# define RENDERDOC_CC
#else
# error "Unknown platform"
#endif
#ifdef __cplusplus
extern "C" {
#endif
//////////////////////////////////////////////////////////////////////////////////////////////////
// Constants not used directly in below API
// This is a GUID/magic value used for when applications pass a path where shader debug
// information can be found to match up with a stripped shader.
// the define can be used like so: const GUID RENDERDOC_ShaderDebugMagicValue =
// RENDERDOC_ShaderDebugMagicValue_value
#define RENDERDOC_ShaderDebugMagicValue_struct \
{ \
0xeab25520, 0x6670, 0x4865, 0x84, 0x29, 0x6c, 0x8, 0x51, 0x54, 0x00, 0xff \
}
// as an alternative when you want a byte array (assuming x86 endianness):
#define RENDERDOC_ShaderDebugMagicValue_bytearray \
{ \
0x20, 0x55, 0xb2, 0xea, 0x70, 0x66, 0x65, 0x48, 0x84, 0x29, 0x6c, 0x8, 0x51, 0x54, 0x00, \
0xff \
}
// truncated version when only a uint64_t is available (e.g. Vulkan tags):
#define RENDERDOC_ShaderDebugMagicValue_truncated 0x48656670eab25520ULL
//////////////////////////////////////////////////////////////////////////////////////////////////
// RenderDoc capture options
//
typedef enum
{
// Allow the application to enable vsync
//
// Default - enabled
//
// 1 - The application can enable or disable vsync at will
// 0 - vsync is force disabled
eRENDERDOC_Option_AllowVSync = 0,
// Allow the application to enable fullscreen
//
// Default - enabled
//
// 1 - The application can enable or disable fullscreen at will
// 0 - fullscreen is force disabled
eRENDERDOC_Option_AllowFullscreen = 1,
// Record API debugging events and messages
//
// Default - disabled
//
// 1 - Enable built-in API debugging features and records the results into
// the capture, which is matched up with events on replay
// 0 - no API debugging is forcibly enabled
eRENDERDOC_Option_APIValidation = 2,
eRENDERDOC_Option_DebugDeviceMode = 2, // deprecated name of this enum
// Capture CPU callstacks for API events
//
// Default - disabled
//
// 1 - Enables capturing of callstacks
// 0 - no callstacks are captured
eRENDERDOC_Option_CaptureCallstacks = 3,
// When capturing CPU callstacks, only capture them from drawcalls.
// This option does nothing without the above option being enabled
//
// Default - disabled
//
// 1 - Only captures callstacks for drawcall type API events.
// Ignored if CaptureCallstacks is disabled
// 0 - Callstacks, if enabled, are captured for every event.
eRENDERDOC_Option_CaptureCallstacksOnlyDraws = 4,
// Specify a delay in seconds to wait for a debugger to attach, after
// creating or injecting into a process, before continuing to allow it to run.
//
// 0 indicates no delay, and the process will run immediately after injection
//
// Default - 0 seconds
//
eRENDERDOC_Option_DelayForDebugger = 5,
// Verify any writes to mapped buffers, by checking the memory after the
// bounds of the returned pointer to detect any modification.
//
// Default - disabled
//
// 1 - Verify any writes to mapped buffers
// 0 - No verification is performed, and overwriting bounds may cause
// crashes or corruption in RenderDoc
eRENDERDOC_Option_VerifyMapWrites = 6,
// Hooks any system API calls that create child processes, and injects
// RenderDoc into them recursively with the same options.
//
// Default - disabled
//
// 1 - Hooks into spawned child processes
// 0 - Child processes are not hooked by RenderDoc
eRENDERDOC_Option_HookIntoChildren = 7,
// By default RenderDoc only includes resources in the final capture necessary
// for that frame, this allows you to override that behaviour.
//
// Default - disabled
//
// 1 - all live resources at the time of capture are included in the capture
// and available for inspection
// 0 - only the resources referenced by the captured frame are included
eRENDERDOC_Option_RefAllResources = 8,
// **NOTE**: As of RenderDoc v1.1 this option has been deprecated. Setting or
// getting it will be ignored, to allow compatibility with older versions.
// In v1.1 the option acts as if it's always enabled.
//
// By default RenderDoc skips saving initial states for resources where the
// previous contents don't appear to be used, assuming that writes before
// reads indicate previous contents aren't used.
//
// Default - disabled
//
// 1 - initial contents at the start of each captured frame are saved, even if
// they are later overwritten or cleared before being used.
// 0 - unless a read is detected, initial contents will not be saved and will
// appear as black or empty data.
eRENDERDOC_Option_SaveAllInitials = 9,
// In APIs that allow for the recording of command lists to be replayed later,
// RenderDoc may choose to not capture command lists before a frame capture is
// triggered, to reduce overheads. This means any command lists recorded once
// and replayed many times will not be available and may cause a failure to
// capture.
//
// Note this is only true for APIs where multithreading is difficult or
// discouraged. Newer APIs like Vulkan and D3D12 will ignore this option
// and always capture all command lists since the API is heavily oriented
// around it and the overheads have been reduced by API design.
//
// 1 - All command lists are captured from the start of the application
// 0 - Command lists are only captured if their recording begins during
// the period when a frame capture is in progress.
eRENDERDOC_Option_CaptureAllCmdLists = 10,
// Mute API debugging output when the API validation mode option is enabled
//
// Default - enabled
//
// 1 - Mute any API debug messages from being displayed or passed through
// 0 - API debugging is displayed as normal
eRENDERDOC_Option_DebugOutputMute = 11,
} RENDERDOC_CaptureOption;
// Sets an option that controls how RenderDoc behaves on capture.
//
// Returns 1 if the option and value are valid
// Returns 0 if either is invalid and the option is unchanged
typedef int(RENDERDOC_CC *pRENDERDOC_SetCaptureOptionU32)(RENDERDOC_CaptureOption opt,
uint32_t val);
typedef int(RENDERDOC_CC *pRENDERDOC_SetCaptureOptionF32)(RENDERDOC_CaptureOption opt, float val);
// Gets the current value of an option as a uint32_t
//
// If the option is invalid, 0xffffffff is returned
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetCaptureOptionU32)(RENDERDOC_CaptureOption opt);
// Gets the current value of an option as a float
//
// If the option is invalid, -FLT_MAX is returned
typedef float(RENDERDOC_CC *pRENDERDOC_GetCaptureOptionF32)(RENDERDOC_CaptureOption opt);
typedef enum
{
// '0' - '9' matches ASCII values
eRENDERDOC_Key_0 = 0x30,
eRENDERDOC_Key_1 = 0x31,
eRENDERDOC_Key_2 = 0x32,
eRENDERDOC_Key_3 = 0x33,
eRENDERDOC_Key_4 = 0x34,
eRENDERDOC_Key_5 = 0x35,
eRENDERDOC_Key_6 = 0x36,
eRENDERDOC_Key_7 = 0x37,
eRENDERDOC_Key_8 = 0x38,
eRENDERDOC_Key_9 = 0x39,
// 'A' - 'Z' matches ASCII values
eRENDERDOC_Key_A = 0x41,
eRENDERDOC_Key_B = 0x42,
eRENDERDOC_Key_C = 0x43,
eRENDERDOC_Key_D = 0x44,
eRENDERDOC_Key_E = 0x45,
eRENDERDOC_Key_F = 0x46,
eRENDERDOC_Key_G = 0x47,
eRENDERDOC_Key_H = 0x48,
eRENDERDOC_Key_I = 0x49,
eRENDERDOC_Key_J = 0x4A,
eRENDERDOC_Key_K = 0x4B,
eRENDERDOC_Key_L = 0x4C,
eRENDERDOC_Key_M = 0x4D,
eRENDERDOC_Key_N = 0x4E,
eRENDERDOC_Key_O = 0x4F,
eRENDERDOC_Key_P = 0x50,
eRENDERDOC_Key_Q = 0x51,
eRENDERDOC_Key_R = 0x52,
eRENDERDOC_Key_S = 0x53,
eRENDERDOC_Key_T = 0x54,
eRENDERDOC_Key_U = 0x55,
eRENDERDOC_Key_V = 0x56,
eRENDERDOC_Key_W = 0x57,
eRENDERDOC_Key_X = 0x58,
eRENDERDOC_Key_Y = 0x59,
eRENDERDOC_Key_Z = 0x5A,
// leave the rest of the ASCII range free
// in case we want to use it later
eRENDERDOC_Key_NonPrintable = 0x100,
eRENDERDOC_Key_Divide,
eRENDERDOC_Key_Multiply,
eRENDERDOC_Key_Subtract,
eRENDERDOC_Key_Plus,
eRENDERDOC_Key_F1,
eRENDERDOC_Key_F2,
eRENDERDOC_Key_F3,
eRENDERDOC_Key_F4,
eRENDERDOC_Key_F5,
eRENDERDOC_Key_F6,
eRENDERDOC_Key_F7,
eRENDERDOC_Key_F8,
eRENDERDOC_Key_F9,
eRENDERDOC_Key_F10,
eRENDERDOC_Key_F11,
eRENDERDOC_Key_F12,
eRENDERDOC_Key_Home,
eRENDERDOC_Key_End,
eRENDERDOC_Key_Insert,
eRENDERDOC_Key_Delete,
eRENDERDOC_Key_PageUp,
eRENDERDOC_Key_PageDn,
eRENDERDOC_Key_Backspace,
eRENDERDOC_Key_Tab,
eRENDERDOC_Key_PrtScrn,
eRENDERDOC_Key_Pause,
eRENDERDOC_Key_Max,
} RENDERDOC_InputButton;
// Sets which key or keys can be used to toggle focus between multiple windows
//
// If keys is NULL or num is 0, toggle keys will be disabled
typedef void(RENDERDOC_CC *pRENDERDOC_SetFocusToggleKeys)(RENDERDOC_InputButton *keys, int num);
// Sets which key or keys can be used to capture the next frame
//
// If keys is NULL or num is 0, captures keys will be disabled
typedef void(RENDERDOC_CC *pRENDERDOC_SetCaptureKeys)(RENDERDOC_InputButton *keys, int num);
typedef enum
{
// This single bit controls whether the overlay is enabled or disabled globally
eRENDERDOC_Overlay_Enabled = 0x1,
// Show the average framerate over several seconds as well as min/max
eRENDERDOC_Overlay_FrameRate = 0x2,
// Show the current frame number
eRENDERDOC_Overlay_FrameNumber = 0x4,
// Show a list of recent captures, and how many captures have been made
eRENDERDOC_Overlay_CaptureList = 0x8,
// Default values for the overlay mask
eRENDERDOC_Overlay_Default = (eRENDERDOC_Overlay_Enabled | eRENDERDOC_Overlay_FrameRate |
eRENDERDOC_Overlay_FrameNumber | eRENDERDOC_Overlay_CaptureList),
// Enable all bits
eRENDERDOC_Overlay_All = ~0U,
// Disable all bits
eRENDERDOC_Overlay_None = 0,
} RENDERDOC_OverlayBits;
// returns the overlay bits that have been set
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetOverlayBits)();
// sets the overlay bits with an and & or mask
typedef void(RENDERDOC_CC *pRENDERDOC_MaskOverlayBits)(uint32_t And, uint32_t Or);
// this function will attempt to shut down RenderDoc.
//
// Note: that this will only work correctly if done immediately after
// the dll is loaded, before any API work happens. RenderDoc will remove its
// injected hooks and shut down. Behaviour is undefined if this is called
// after any API functions have been called.
typedef void(RENDERDOC_CC *pRENDERDOC_Shutdown)();
// This function will unload RenderDoc's crash handler.
//
// If you use your own crash handler and don't want RenderDoc's handler to
// intercede, you can call this function to unload it and any unhandled
// exceptions will pass to the next handler.
typedef void(RENDERDOC_CC *pRENDERDOC_UnloadCrashHandler)();
// Sets the capture file path template
//
// pathtemplate is a UTF-8 string that gives a template for how captures will be named
// and where they will be saved.
//
// Any extension is stripped off the path, and captures are saved in the directory
// specified, and named with the filename and the frame number appended. If the
// directory does not exist it will be created, including any parent directories.
//
// If pathtemplate is NULL, the template will remain unchanged
//
// Example:
//
// SetCaptureFilePathTemplate("my_captures/example");
//
// Capture #1 -> my_captures/example_frame123.rdc
// Capture #2 -> my_captures/example_frame456.rdc
typedef void(RENDERDOC_CC *pRENDERDOC_SetCaptureFilePathTemplate)(const char *pathtemplate);
// returns the current capture path template, see SetCaptureFileTemplate above, as a UTF-8 string
typedef const char *(RENDERDOC_CC *pRENDERDOC_GetCaptureFilePathTemplate)();
// DEPRECATED: compatibility for code compiled against pre-1.1.2 headers.
typedef void(RENDERDOC_CC *pRENDERDOC_SetLogFilePathTemplate)(const char *pathtemplate);
typedef const char *(RENDERDOC_CC *pRENDERDOC_GetLogFilePathTemplate)();
// returns the number of captures that have been made
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetNumCaptures)();
// This function returns the details of a capture, by index. New captures are added
// to the end of the list.
//
// filename will be filled with the absolute path to the capture file, as a UTF-8 string
// pathlength will be written with the length in bytes of the filename string
// timestamp will be written with the time of the capture, in seconds since the Unix epoch
//
// Any of the parameters can be NULL and they'll be skipped.
//
// The function will return 1 if the capture index is valid, or 0 if the index is invalid
// If the index is invalid, the values will be unchanged
//
// Note: when captures are deleted in the UI they will remain in this list, so the
// capture path may not exist anymore.
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_GetCapture)(uint32_t idx,
char *filename,
uint32_t *pathlength,
uint64_t *timestamp);
// returns 1 if the RenderDoc UI is connected to this application, 0 otherwise
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_IsTargetControlConnected)();
// DEPRECATED: compatibility for code compiled against pre-1.1.1 headers.
// This was renamed to IsTargetControlConnected in API 1.1.1, the old typedef is kept here for
// backwards compatibility with old code, it is castable either way since it's ABI compatible
// as the same function pointer type.
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_IsRemoteAccessConnected)();
// This function will launch the Replay UI associated with the RenderDoc library injected
// into the running application.
//
// if connectTargetControl is 1, the Replay UI will be launched with a command line parameter
// to connect to this application
// cmdline is the rest of the command line, as a UTF-8 string. E.g. a captures to open
// if cmdline is NULL, the command line will be empty.
//
// returns the PID of the replay UI if successful, 0 if not successful.
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_LaunchReplayUI)(uint32_t connectTargetControl,
const char *cmdline);
// RenderDoc can return a higher version than requested if it's backwards compatible,
// this function returns the actual version returned. If a parameter is NULL, it will be
// ignored and the others will be filled out.
typedef void(RENDERDOC_CC *pRENDERDOC_GetAPIVersion)(int *major, int *minor, int *patch);
//////////////////////////////////////////////////////////////////////////
// Capturing functions
//
// A device pointer is a pointer to the API's root handle.
//
// This would be an ID3D11Device, HGLRC/GLXContext, ID3D12Device, etc
typedef void *RENDERDOC_DevicePointer;
// A window handle is the OS's native window handle
//
// This would be an HWND, GLXDrawable, etc
typedef void *RENDERDOC_WindowHandle;
// A helper macro for Vulkan, where the device handle cannot be used directly.
//
// Passing the VkInstance to this macro will return the RENDERDOC_DevicePointer to use.
//
// Specifically, the value needed is the dispatch table pointer, which sits as the first
// pointer-sized object in the memory pointed to by the VkInstance. Thus we cast to a void** and
// indirect once.
#define RENDERDOC_DEVICEPOINTER_FROM_VKINSTANCE(inst) (*((void **)(inst)))
// This sets the RenderDoc in-app overlay in the API/window pair as 'active' and it will
// respond to keypresses. Neither parameter can be NULL
typedef void(RENDERDOC_CC *pRENDERDOC_SetActiveWindow)(RENDERDOC_DevicePointer device,
RENDERDOC_WindowHandle wndHandle);
// capture the next frame on whichever window and API is currently considered active
typedef void(RENDERDOC_CC *pRENDERDOC_TriggerCapture)();
// capture the next N frames on whichever window and API is currently considered active
typedef void(RENDERDOC_CC *pRENDERDOC_TriggerMultiFrameCapture)(uint32_t numFrames);
// When choosing either a device pointer or a window handle to capture, you can pass NULL.
// Passing NULL specifies a 'wildcard' match against anything. This allows you to specify
// any API rendering to a specific window, or a specific API instance rendering to any window,
// or in the simplest case of one window and one API, you can just pass NULL for both.
//
// In either case, if there are two or more possible matching (device,window) pairs it
// is undefined which one will be captured.
//
// Note: for headless rendering you can pass NULL for the window handle and either specify
// a device pointer or leave it NULL as above.
// Immediately starts capturing API calls on the specified device pointer and window handle.
//
// If there is no matching thing to capture (e.g. no supported API has been initialised),
// this will do nothing.
//
// The results are undefined (including crashes) if two captures are started overlapping,
// even on separate devices and/oror windows.
typedef void(RENDERDOC_CC *pRENDERDOC_StartFrameCapture)(RENDERDOC_DevicePointer device,
RENDERDOC_WindowHandle wndHandle);
// Returns whether or not a frame capture is currently ongoing anywhere.
//
// This will return 1 if a capture is ongoing, and 0 if there is no capture running
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_IsFrameCapturing)();
// Ends capturing immediately.
//
// This will return 1 if the capture succeeded, and 0 if there was an error capturing.
typedef uint32_t(RENDERDOC_CC *pRENDERDOC_EndFrameCapture)(RENDERDOC_DevicePointer device,
RENDERDOC_WindowHandle wndHandle);
//////////////////////////////////////////////////////////////////////////////////////////////////
// RenderDoc API versions
//
// RenderDoc uses semantic versioning (http://semver.org/).
//
// MAJOR version is incremented when incompatible API changes happen.
// MINOR version is incremented when functionality is added in a backwards-compatible manner.
// PATCH version is incremented when backwards-compatible bug fixes happen.
//
// Note that this means the API returned can be higher than the one you might have requested.
// e.g. if you are running against a newer RenderDoc that supports 1.0.1, it will be returned
// instead of 1.0.0. You can check this with the GetAPIVersion entry point
typedef enum
{
eRENDERDOC_API_Version_1_0_0 = 10000, // RENDERDOC_API_1_0_0 = 1 00 00
eRENDERDOC_API_Version_1_0_1 = 10001, // RENDERDOC_API_1_0_1 = 1 00 01
eRENDERDOC_API_Version_1_0_2 = 10002, // RENDERDOC_API_1_0_2 = 1 00 02
eRENDERDOC_API_Version_1_1_0 = 10100, // RENDERDOC_API_1_1_0 = 1 01 00
eRENDERDOC_API_Version_1_1_1 = 10101, // RENDERDOC_API_1_1_1 = 1 01 01
eRENDERDOC_API_Version_1_1_2 = 10102, // RENDERDOC_API_1_1_2 = 1 01 02
} RENDERDOC_Version;
// API version changelog:
//
// 1.0.0 - initial release
// 1.0.1 - Bugfix: IsFrameCapturing() was returning false for captures that were triggered
// by keypress or TriggerCapture, instead of Start/EndFrameCapture.
// 1.0.2 - Refactor: Renamed eRENDERDOC_Option_DebugDeviceMode to eRENDERDOC_Option_APIValidation
// 1.1.0 - Add feature: TriggerMultiFrameCapture(). Backwards compatible with 1.0.x since the new
// function pointer is added to the end of the struct, the original layout is identical
// 1.1.1 - Refactor: Renamed remote access to target control (to better disambiguate from remote
// replay/remote server concept in replay UI)
// 1.1.2 - Refactor: Renamed "log file" in function names to just capture, to clarify that these
// are captures and not debug logging files. This is the first API version in the v1.0
// branch.
// eRENDERDOC_API_Version_1_1_0
typedef struct
{
pRENDERDOC_GetAPIVersion GetAPIVersion;
pRENDERDOC_SetCaptureOptionU32 SetCaptureOptionU32;
pRENDERDOC_SetCaptureOptionF32 SetCaptureOptionF32;
pRENDERDOC_GetCaptureOptionU32 GetCaptureOptionU32;
pRENDERDOC_GetCaptureOptionF32 GetCaptureOptionF32;
pRENDERDOC_SetFocusToggleKeys SetFocusToggleKeys;
pRENDERDOC_SetCaptureKeys SetCaptureKeys;
pRENDERDOC_GetOverlayBits GetOverlayBits;
pRENDERDOC_MaskOverlayBits MaskOverlayBits;
pRENDERDOC_Shutdown Shutdown;
pRENDERDOC_UnloadCrashHandler UnloadCrashHandler;
pRENDERDOC_SetLogFilePathTemplate SetLogFilePathTemplate;
pRENDERDOC_GetLogFilePathTemplate GetLogFilePathTemplate;
pRENDERDOC_GetNumCaptures GetNumCaptures;
pRENDERDOC_GetCapture GetCapture;
pRENDERDOC_TriggerCapture TriggerCapture;
pRENDERDOC_IsRemoteAccessConnected IsRemoteAccessConnected;
pRENDERDOC_LaunchReplayUI LaunchReplayUI;
pRENDERDOC_SetActiveWindow SetActiveWindow;
pRENDERDOC_StartFrameCapture StartFrameCapture;
pRENDERDOC_IsFrameCapturing IsFrameCapturing;
pRENDERDOC_EndFrameCapture EndFrameCapture;
pRENDERDOC_TriggerMultiFrameCapture TriggerMultiFrameCapture;
} RENDERDOC_API_1_1_0;
typedef RENDERDOC_API_1_1_0 RENDERDOC_API_1_0_0;
typedef RENDERDOC_API_1_1_0 RENDERDOC_API_1_0_1;
typedef RENDERDOC_API_1_1_0 RENDERDOC_API_1_0_2;
// although this structure is identical to RENDERDOC_API_1_1_0, the member
// IsRemoteAccessConnected was renamed to IsTargetControlConnected. So that
// old code can still compile with a new header, we must declare a new struct
// type. It can be casted back and forth though, so we will still return a
// pointer to this type for all previous API versions - the above struct is
// purely legacy for compilation compatibility
// eRENDERDOC_API_Version_1_1_1
typedef struct
{
pRENDERDOC_GetAPIVersion GetAPIVersion;
pRENDERDOC_SetCaptureOptionU32 SetCaptureOptionU32;
pRENDERDOC_SetCaptureOptionF32 SetCaptureOptionF32;
pRENDERDOC_GetCaptureOptionU32 GetCaptureOptionU32;
pRENDERDOC_GetCaptureOptionF32 GetCaptureOptionF32;
pRENDERDOC_SetFocusToggleKeys SetFocusToggleKeys;
pRENDERDOC_SetCaptureKeys SetCaptureKeys;
pRENDERDOC_GetOverlayBits GetOverlayBits;
pRENDERDOC_MaskOverlayBits MaskOverlayBits;
pRENDERDOC_Shutdown Shutdown;
pRENDERDOC_UnloadCrashHandler UnloadCrashHandler;
pRENDERDOC_SetLogFilePathTemplate SetLogFilePathTemplate;
pRENDERDOC_GetLogFilePathTemplate GetLogFilePathTemplate;
pRENDERDOC_GetNumCaptures GetNumCaptures;
pRENDERDOC_GetCapture GetCapture;
pRENDERDOC_TriggerCapture TriggerCapture;
pRENDERDOC_IsTargetControlConnected IsTargetControlConnected;
pRENDERDOC_LaunchReplayUI LaunchReplayUI;
pRENDERDOC_SetActiveWindow SetActiveWindow;
pRENDERDOC_StartFrameCapture StartFrameCapture;
pRENDERDOC_IsFrameCapturing IsFrameCapturing;
pRENDERDOC_EndFrameCapture EndFrameCapture;
pRENDERDOC_TriggerMultiFrameCapture TriggerMultiFrameCapture;
} RENDERDOC_API_1_1_1;
// similarly to above, we renamed Get/SetLogFilePathTemplate to Get/SetCaptureFilePathTemplate.
// We thus declare a new struct so that code that was referencing the RENDERDOC_API_1_1_1 struct
// can still compile without changes, but new code will use the new struct members
// eRENDERDOC_API_Version_1_1_2
typedef struct
{
pRENDERDOC_GetAPIVersion GetAPIVersion;
pRENDERDOC_SetCaptureOptionU32 SetCaptureOptionU32;
pRENDERDOC_SetCaptureOptionF32 SetCaptureOptionF32;
pRENDERDOC_GetCaptureOptionU32 GetCaptureOptionU32;
pRENDERDOC_GetCaptureOptionF32 GetCaptureOptionF32;
pRENDERDOC_SetFocusToggleKeys SetFocusToggleKeys;
pRENDERDOC_SetCaptureKeys SetCaptureKeys;
pRENDERDOC_GetOverlayBits GetOverlayBits;
pRENDERDOC_MaskOverlayBits MaskOverlayBits;
pRENDERDOC_Shutdown Shutdown;
pRENDERDOC_UnloadCrashHandler UnloadCrashHandler;
pRENDERDOC_SetCaptureFilePathTemplate SetCaptureFilePathTemplate;
pRENDERDOC_GetCaptureFilePathTemplate GetCaptureFilePathTemplate;
pRENDERDOC_GetNumCaptures GetNumCaptures;
pRENDERDOC_GetCapture GetCapture;
pRENDERDOC_TriggerCapture TriggerCapture;
pRENDERDOC_IsTargetControlConnected IsTargetControlConnected;
pRENDERDOC_LaunchReplayUI LaunchReplayUI;
pRENDERDOC_SetActiveWindow SetActiveWindow;
pRENDERDOC_StartFrameCapture StartFrameCapture;
pRENDERDOC_IsFrameCapturing IsFrameCapturing;
pRENDERDOC_EndFrameCapture EndFrameCapture;
pRENDERDOC_TriggerMultiFrameCapture TriggerMultiFrameCapture;
} RENDERDOC_API_1_1_2;
//////////////////////////////////////////////////////////////////////////////////////////////////
// RenderDoc API entry point
//
// This entry point can be obtained via GetProcAddress/dlsym if RenderDoc is available.
//
// The name is the same as the typedef - "RENDERDOC_GetAPI"
//
// This function is not thread safe, and should not be called on multiple threads at once.
// Ideally, call this once as early as possible in your application's startup, before doing
// any API work, since some configuration functionality etc has to be done also before
// initialising any APIs.
//
// Parameters:
// version is a single value from the RENDERDOC_Version above.
//
// outAPIPointers will be filled out with a pointer to the corresponding struct of function
// pointers.
//
// Returns:
// 1 - if the outAPIPointers has been filled with a pointer to the API struct requested
// 0 - if the requested version is not supported or the arguments are invalid.
//
typedef int(RENDERDOC_CC *pRENDERDOC_GetAPI)(RENDERDOC_Version version, void **outAPIPointers);
#ifdef __cplusplus
} // extern "C"
#endif