Add Doxygen documentation support for ReShade API

Author: crosire

Doxyfile

@@ -0,0 +1,31 @@
+PROJECT_NAME           = "ReShade"
+PROJECT_BRIEF          = "A generic post-processing injector for games and video software."
+PROJECT_LOGO           = ./res/main_icon_small.png
+
+INPUT                  = ./include ./REFERENCE.md
+EXCLUDE                = ./include/imgui_function_table.hpp
+FILE_PATTERNS          = *.c *.cpp *.h *.hpp *.inl
+EXCLUDE_SYMBOLS        = addon_event_traits
+USE_MDFILE_AS_MAINPAGE = ./REFERENCE.md
+
+OUTPUT_DIRECTORY       = ./build
+
+GENERATE_XML           = YES
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+
+# Parser configuration
+
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+
+# Preprocessor configuration
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+PREDEFINED             = __declspec(x)=
+SKIP_FUNCTION_MACROS   = YES

README.md

@@ -3,7 +3,7 @@ ReShade
 
 This is a generic post-processing injector for games and video software. It exposes an automated way to access both frame color and depth information and a custom shader language called ReShade FX to write effects like ambient occlusion, depth of field, color correction and more which work everywhere.
 
-ReShade can optionally load **add-ons**, DLLs that make use of the ReShade API to extend functionality of both ReShade and/or the application ReShade is being applied to. To get started on how to write your own add-on, check out the [documentation in the include directory of this repository](include/README.md).
+ReShade can optionally load **add-ons**, DLLs that make use of the ReShade API to extend functionality of both ReShade and/or the application ReShade is being applied to. To get started on how to write your own add-on, check out the [API reference](REFERENCE.md).
 
 The ReShade FX shader compiler contained in this repository is standalone, so can be integrated into other projects as well. Simply add all `source/effect_*.*` files to your project and use it similar to the [fxc example](tools/fxc.cpp).
 

include/README.md REFERENCE.mdinclude/README.md renamed to REFERENCE.md

@@ -3,7 +3,7 @@ ReShade API
 
 The ReShade API is a toolset that lets you interact with the resources and rendering commands of the application ReShade is loaded into via events. It [abstracts](#abstraction) away differences between the various underlying graphics API ReShade supports (Direct3D 9/10/11/12, OpenGL and Vulkan) to make it possible to write add-ons that work across a wide range of applications, regardless of the graphics API they use.
 
-A ReShade add-on is simply a DLL that uses the header-only ReShade API to register events and do work in the callbacks. There are no further requirements, no functions need to be exported and no libraries need to be linked against. Simply add this include directory to your DLL project and include the [`reshade.hpp`](reshade.hpp) header to get started.
+A ReShade add-on is simply a DLL that uses the header-only ReShade API to register events and do work in the callbacks. There are no further requirements, no functions need to be exported and no libraries need to be linked against. Simply add this include directory to your DLL project and include the `reshade.hpp` header to get started.
 
 Here is a very basic code example of an add-on that registers a callback that gets executed every time a new frame is presented to the screen:
 
@@ -45,7 +45,7 @@ For more complex examples, see the [examples directory in this repository](../ex
 ## Overlays
 
 It is also supported to add an overlay, which can e.g. be used to display debug information or interact with the user in-application.
-Overlays are created with the use of [Dear ImGui](https://github.com/ocornut/imgui/). Including the [`reshade.hpp`](reshade.hpp) header after `imgui.h` will automatically overwrite all Dear ImGui functions to use the instance created and managed by ReShade. This means all you have to do is include these two headers, define the function table variable in one of your source code file and use Dear ImGui as usual (without actually having to build its source code files, only the header files are needed):
+Overlays are created with the use of [Dear ImGui](https://github.com/ocornut/imgui/). Including the `reshade.hpp` header after `imgui.h` will automatically overwrite all Dear ImGui functions to use the instance created and managed by ReShade. This means all you have to do is include these two headers, define the function table variable in one of your source code file and use Dear ImGui as usual (without actually having to build its source code files, only the header files are needed):
 
 ```cpp
 #include <imgui.h>
@@ -105,28 +105,31 @@ BOOL WINAPI DllMain(HINSTANCE hinstDLL, DWORD fdwReason, LPVOID)
 
 The graphics API abstraction is modeled after the Vulkan API, so much of the terminology used should be familiar to developers that have used Vulkan before.
 
-Detailed inline documentation for all classes and methods can be found inside the headers (see [`reshade_api.hpp`](reshade_api.hpp) for the abstraction object classes and [`reshade_events.hpp`](reshade_events.hpp) for a list of available events).
+Detailed inline documentation for all classes and methods can be found inside the headers (see `reshade_api.hpp` for the abstraction object classes and `reshade_events.hpp` for a list of available events).
 
 The base object everything else is created from is a `reshade::api::device`. This represents a logical rendering device that is typically mapped to a physical GPU (but may also be mapped to multiple GPUs). ReShade will call the `reshade::addon_event::init_device` event after the application created a device, which can e.g. be used to do some initialization work that only has to happen once. The `reshade::addon_event::destroy_device` event is called before this device is destroyed again, which can be used to perform clean up work.
-```c++
-using namespace reshade::api;
-
+```cpp
 // Example callback function that can be registered via 'reshade::register_event<reshade::addon_event::init_device>(on_init_device)'.
-static void on_init_device(device *device)
+static void on_init_device(reshade::api::device *device)
 {
     // In case one wants to do something with the native graphics API object, rather than doing all work
     // through the ReShade API, can retrieve it as follows:
-    if (device->get_api() == device_api::d3d11)
+    if (device->get_api() == reshade::api::device_api::d3d11)
     {
         ID3D11Device *const d3d11_device = (ID3D11Device *)device->get_native_object();
         // ...
     }
 
     // But preferably things should be done through the graphics API abstraction.
     // E.g. to create a new 800x600 texture in GPU memory, call 'reshade::api::device::create_resource()' like this:
-    resource texture = {};
-    const resource_desc desc(800, 600, 1, 1, format::r8g8b8a8_unorm, 1, memory_heap::gpu_only, resource_usage::shader_resource | resource_usage::render_target);
-    if (!device->create_resource(desc, nullptr, resource_usage::undefined, &texture))
+    reshade::api::resource texture = {};
+    const reshade::api::resource_desc desc(
+        800, 600, 1, 1,
+        reshade::api::format::r8g8b8a8_unorm,
+        1,
+        reshade::api::memory_heap::gpu_only,
+        reshade::api::resource_usage::shader_resource | reshade::api::resource_usage::render_target);
+    if (!device->create_resource(desc, nullptr, reshade::api::resource_usage::undefined, &texture))
     {
         // Error handling ...
     }
@@ -137,17 +140,15 @@ static void on_init_device(device *device)
 
 To execute rendering commands, an application has to record them into a `reshade::api::command_list` and then submit to a `reshade::api::command_queue`. In some graphics APIs there is only a single implicit command list and queue, but modern ones like Direct3D 12 and Vulkan allow the creation of multiple command lists and queues for more efficient multi-threaded rendering. ReShade will call the `reshade::addon_event::init_command_list` and `reshade::addon_event::init_command_queue` events after any such object was created by the application (including the implicit ones for older graphics APIs). Similarily, `reshade::addon_event::destroy_command_list` and `reshade::addon_event::destroy_command_queue` are called upon their destruction.\
 ReShade will also pass the current command list object to every command event, like `reshade::addon_event::draw`, `reshade::addon_event::dispatch` and so on, which can be used to add additional commands to that command list or replace those of the application.
-```c++
-using namespace reshade::api;
-
+```cpp
 // Example callback function that can be registered via 'reshade::register_event<reshade::addon_event::draw>(on_draw)'.
-static bool on_draw(command_list *cmd_list, uint32_t vertices, uint32_t instances, uint32_t first_vertex, uint32_t first_instance)
+static bool on_draw(reshade::api::command_list *cmd_list, uint32_t vertices, uint32_t instances, uint32_t first_vertex, uint32_t first_instance)
 {
     // Clear the current render targets to red before every time a single triangle is drawn
     if (vertices == 3 && instances == 1)
     {
         const float clear_color[4] = { 1.0f, 0.0f, 0.0f, 1.0f };
-        cmd_list->clear_attachments(attachment_type::color, clear_color, 0, 0);
+        cmd_list->clear_attachments(reshade::api::attachment_type::color, clear_color, 0, 0);
     }
 
     // Return 'true' to prevent this application command from actually being executed (e.g. because already having added a new command that should replace it via 'cmd_list->draw(...)' or similar).
@@ -157,11 +158,9 @@ static bool on_draw(command_list *cmd_list, uint32_t vertices, uint32_t instance
 ```
 
 Showing results on the screen is done through a `reshade::api::swapchain` object. This is a collection of back buffers that the application can render into, which will eventually be presented to the screen. There may be multiple swap chains, if for example the application is rendering to multiple windows, or to a screen and a VR headset. ReShade again will call the `reshade::addon_event::init_swapchain` event after such an object was created by the application (and `reshade::addon_event::destroy_swapchain` on destruction). In addition ReShade will call the `reshade::addon_event::create_swapchain` event before the swap chain is created, so an add-on may modify its description before that happens. For example, to force the resolution to a specific value, one can do the following:
-```c++
-using namespace reshade::api;
-
+```cpp
 // Example callback function that can be registered via 'reshade::register_event<reshade::addon_event::create_swapchain>(on_create_swapchain)'.
-static bool on_create_swapchain(resource_desc &buffer_desc, void *hwnd)
+static bool on_create_swapchain(reshade::api::resource_desc &buffer_desc, void *hwnd)
 {
     // Change resolution to 1920x1080 if the application is trying to create a swap chain at 800x600.
     if (buffer_desc.texture.width == 800 &&

include/reshade.hpp

@@ -142,7 +142,7 @@ namespace reshade
 	/// Registers an overlay with ReShade.
 	/// <para>The callback function is then called whenever the ReShade overlay is visible and allows adding Dear ImGui widgets for user interaction.</para>
 	/// </summary>
-	/// <param name="title">A null-terminated title string, or <c>nullptr</c> to register a settings overlay for this add-on.</param>
+	/// <param name="title">A null-terminated title string, or <see langword="nullptr"/> to register a settings overlay for this add-on.</param>
 	/// <param name="callback">Pointer to the callback function.</param>
 	inline void register_overlay(const char *title, void(*callback)(reshade::api::effect_runtime *runtime, void *imgui_context))
 	{