throw_if_failed

Generated from engine/render/throw_if_failed.h at 862e08b. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.

Browse the render module

#include "engine/render/throw_if_failed.h" · namespace labrador

WHERE THIS LIVES, and why it is not in core/. Its only engine includers are the two Direct3D backends - three translation units each - so the rule that a backend's headers are its own leaves two shapes: a copy in d3d11/ and a copy in d3d12/, or one file here that neither owns. It is the second, for the reason render/sprite.hlsl beside it gives for being one file rather than one per backend: a second copy is a file that can silently disagree with the first, and what these two would disagree about is an exception type whose whole point is that a catch site cannot tell (tests/render/throw_if_failed_tests.cpp pins it, and compiles in every configuration).

NOT core/. This file carries <Windows.h> and an HRESULT, which is exactly what the one module everything may lean on must not - and core/registry.h keeps COM out for the same reason, specialising for a ComPtr in render/d3d11/backend.h, where COM is already in scope.

THE NAMES ARE MICROSOFT'S AND STAY THAT WAY. NOTICE lists this file among those adopted from the DirectX samples. ThrowIfFailed is PascalCase where CONVENTIONS wants snake_case and com_exception is snake_case where it wants PascalCase, because upstream spells them so - and one of the callers is upstream's own file, carried with upstream's naming: engine/render/d3d11/device_resources.cpp reaches it at fifteen sites. Renaming would make that file call an engine function in the engine's style, which is the one thing NOTICE says these files do not do.

class com_exception

class com_exception : public std::runtime_error

Helper class for COM exceptions

std::runtime_error, NOT std::exception, AND THE DIFFERENCE IS A CONTRACT. render/resource_factory.h declares that add_texture_asset throws std::runtime_error naming the texture and the format when the device will not take it. The GL backend does exactly that at four sites; both Direct3D backends reach this class instead, and deriving from std::runtime_error here is what holds every ThrowIfFailed site to that contract at once. A backend is free to keep throwing this, which is the point.

The message is formatted once, in the constructor, and held by the base - not written into a function-local static on each call to what(), which two live com_exceptions would share.

com_exception

explicit com_exception(HRESULT hr);

Not noexcept, and it cannot be: the base stores a string. Nothing constructs one of these outside a throw expression.

ThrowIfFailed

inline void ThrowIfFailed(HRESULT hr);

Helper utility converts D3D API failures into exceptions.

In the samples and tests

The files that include this header directly. A file can also reach it through another header.

• tests/render/ throw_if_failed_tests.cpp