From 49121937cf45b248cd90e1b4de31e17e6fdbc8ad Mon Sep 17 00:00:00 2001 From: Giovanni Mascellani Date: Tue, 1 Oct 2024 18:53:09 +0200 Subject: [PATCH] readme: Document some preprocessor definitions used by vkd3d. --- README | 53 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/README b/README index a45b6d60..efa0d7f7 100644 --- a/README +++ b/README @@ -19,10 +19,9 @@ available or is not recent (>= 3.21), then you can build Wine with `make tools/widl/widl' to avoid building all of Wine. You can then point vkd3d's configure at that widl binary with `WIDL="/path/to/widl"'. -For release builds, you may want to define NDEBUG. If you do not need debug log -messages, you may also consider VKD3D_NO_TRACE_MESSAGES and -VKD3D_NO_DEBUG_MESSAGES. For example, you can pass `CPPFLAGS="-DNDEBUG --DVKD3D_NO_TRACE_MESSAGES"' to configure. +For release builds, you may want to disable debug log messages defining +preprocessor macros VKD3D_NO_TRACE_MESSAGES and VKD3D_NO_DEBUG_MESSAGES. +See the `Preprocessor definitions' section below for more details. ================ Developing vkd3d @@ -50,8 +49,8 @@ Environment variables ===================== Most of the environment variables used by vkd3d are for debugging purposes. The -environment variables are not considered a part of API and might be changed or -removed in the future versions of vkd3d. +environment variables are not considered a stable interface and might be changed +or removed in future versions of vkd3d. Some of debug variables are lists of elements. Elements must be separated by commas or semicolons. @@ -116,6 +115,48 @@ code for adding DXBC checksums, so the official release should be installed from: https://github.com/microsoft/DirectXShaderCompiler/releases +======================== +Preprocessor definitions +======================== + +A number of preprocessor definitions can be used at compilation time to control +the behaviour of the generated binary. You can pass something like +`CPPFLAGS="-DVKD3D_VAR1 -DVKD3D_VAR2"' to the configure script. The preprocessor +variables are not considered a stable interface and might be changed or removed +in future versions of vkd3d. + + * VKD3D_NO_TRACE_MESSAGES - do not emit trace messages in the debug log; this + can be useful in release builds to reduce the size of the binary and make it + slightly faster. + + * VKD3D_NO_DEBUG_MESSAGES - do not emit warn and fixme messages in the debug + log; this will further optimise the binary, but may omit messages that could + help debug problems with vkd3d. + + * VKD3D_NO_ERROR_MESSAGES - do not emit error messages; this will optimise the + binary even more, but may omit very important messages, so it is not + recommended in most circumstances. + + * VKD3D_ABORT_ON_ERR - abort the process as soon as an error message is + emitted; this can be useful for developers to make error conditions as + conspicuous as possible. + + * VKD3D_SHADER_UNSUPPORTED_DXIL - enable DXIL (DirectX Intermediate Language) + support in vkd3d-shader, which is disabled by default because it is not + considered ready for release yet. Please note that this feature is not + currently supported, and it might change in a non-compatible way before it is + released. + + * VKD3D_SHADER_UNSUPPORTED_GLSL - enable GLSL (GL Shading Language) support in + vkd3d-shader, which is disabled by default because it is not considered ready + for release yet. Please note that this feature is not currently supported, + and it might change in a non-compatible way before it is released. + + * VKD3D_SHADER_UNSUPPORTED_MSL - enable MSL (Metal Shading Language) support in + vkd3d-shader, which is disabled by default because it is not considered ready + for release yet. Please note that this feature is not currently supported, + and it might change in a non-compatible way before it is released. + ============================ Testing with the Agility SDK ============================