diff options
Diffstat (limited to 'docs/Ansel_integration_guide.md')
| -rw-r--r-- | docs/Ansel_integration_guide.md | 71 |
1 files changed, 58 insertions, 13 deletions
diff --git a/docs/Ansel_integration_guide.md b/docs/Ansel_integration_guide.md index 2b14987..e75e552 100644 --- a/docs/Ansel_integration_guide.md +++ b/docs/Ansel_integration_guide.md @@ -35,8 +35,8 @@ In order to use Ansel you need * Windows PC with Windows 7 (32-bit or 64-bit) or newer * GeForce GTX 600 series or newer -* Ansel-ready display driver. In order to take advantage of all features of the SDK a driver of version 378.49 or higher - is required. +* Ansel-ready display driver. In order to take advantage of all features of a particular version of the SDK a minum + driver version is required. Please consult the [README.md](../README.md) included with the SDK for details on this. * A game using Dx11 that has integrated the Ansel SDK > **NOTE:** @@ -72,8 +72,8 @@ Ansel will produce images with zero for every pixel - i.e. black. 2. INTEGRATING SDK WITH YOUR GAME --------------------------------- -This Ansel SDK uses four major concepts: Configuration, Session, Camera, and optionally Hints. We will go through each of -them in turn and build up an example of game integration in the process. +This Ansel SDK uses three major concepts: Configuration, Session and Camera. The Ansel SDK also provides optional Hints and User controls APIs. +We will go through each of them in turn and build up an example of game integration in the process. > **NOTE:** Please consult the header files in the Ansel SDK for reference style documentation. @@ -221,7 +221,6 @@ In case <code>kSetConfigurationIncorrectConfiguration</code> is returned, on of * rotational or translational speed multipliers are zero * fovType is neither horizontal, nor vertical * gameWindowHandle field is not set - In case `kSetConfigurationSdkNotLoaded` is returned, the reason is that the Ansel SDK is delay loaded and setConfiguration is called before loading the library via `loadAnselSDKLibrary` (see code under samples folder). @@ -259,7 +258,7 @@ As you will notice the start callback receives an additional SessionConfiguratio struct SessionConfiguration { // User can move the camera during session - bool isTranslationAllowed; + bool isTranslationAllowed; // Camera can be rotated during session bool isRotationAllowed; // FoV can be modified during session @@ -272,7 +271,7 @@ struct SessionConfiguration bool is360MonoAllowed; // Game allows 360 stereo capture during session bool is360StereoAllowed; - // Default constructor not included here + // Default constructor not included here }; ``` @@ -299,9 +298,9 @@ ansel::StartSessionStatus startAnselSessionCallback(ansel::SessionConfiguration& conf.is360StereoAllowed = false; } - g_isAnselSessionActive = true; + g_isAnselSessionActive = true; - return ansel::kAllowed; + return ansel::kAllowed; } ``` @@ -484,14 +483,11 @@ Below we will outline how the hinting API is used to make capture work under the If game developers do not want to use the hinting API to make raw capture work the `isRawAllowed` setting in the `ansel::SessionConfiguration` should be set to false during the startSession callback. This will disable the 'Raw' option in the Ansel UI. -``` -namespace ansel -{ +```cpp // Call this right before setting HDR render target active ANSEL_SDK_API void markHdrBufferBind(uint64_t threadId = 0xFFFFFFFFFFFFFFFFull); // Call this right after the last draw call into the HDR render target ANSEL_SDK_API void markHdrBufferFinished(uint64_t threadId = 0xFFFFFFFFFFFFFFFFull, AnselHintsCopyMode copyMode = kAnselHintsCopyOnPresent); -} ``` To identify the HDR buffer for Ansel call ```markHdrBufferBind``` before binding the buffer to the graphics pipeline. In case the buffer contents is not overwritten before calling ```Present``` @@ -507,6 +503,55 @@ argument specifying if HDR buffer is going to be reused or used in a fashion tha contents will remain in tact until Present call. In case copyMode is set to kAnselHintsCopyImmediately, HDR buffer will be copied upon the next call to the graphics API that Ansel hooks. +### 2.5 USER CONTROLS +Sometimes a game developer is willing to expose some of the game properties in the Ansel UI. One example of this could bee a checkbox allowing +to hide and unhide the main character. Another example would be a slider allowing changing the amount of in-game depth of field effect or any other effect. To achieve that the Ansel SDK provides an optional User controls API. + + + +The basics of the API look like this: + +```cpp + // This function adds a user control defined with the UserControlDesc object + ANSEL_SDK_API UserControlStatus addUserControl(const UserControlDesc& desc); + // Specifies a translation for a control label. + // This function requires a valid lang (a-la "en-US", "es-ES", etc) and a label (non nullptr and non + // empty string without '\n', '\r' and '\t') encoded in utf8. The length of the label should + // not exceed 20 characters not counting the trailing zero + ANSEL_SDK_API UserControlStatus setUserControlLabelLocalization(uint32_t userControlId, const char* lang, const char* labelUtf8); + // This function removes a control that was added previously + ANSEL_SDK_API UserControlStatus removeUserControl(uint32_t userControlId); + // This function returns the current control value + ANSEL_SDK_API UserControlStatus getUserControlValue(uint32_t userControlId, void* value); +``` + +Notice, it is allowed to call any of these functions at any time, even before ```ansel::setConfiguration```. +Currently the supported types of controls are a slider and a checkbox. In order to create a control it is required to create +an object of ```ansel::UserControlDesc```, set it up appropriately and call the ```ansel::addUserControl``` function. +The function also requires a callback of type ```UserControlCallback``` to be passed. This callback will be called +every time user changes the control value in the UI. Please consult the documentation in the headers to learn how to +setup the ```ansel::UserControlDesc``` structure. It is important to notice that ```UserControlInfo::value``` is used +both for adding a control and receiving its value. In either case this pointer should never be nullptr. Its lifetime +is either limited to the ```UserControlCallback``` execution or should be longer than ```ansel::addUserControl``` execution. + +Finally, here is an example of how this API could be used to add a checkbox with additional label localizations: + +```cpp + ansel::UserControlDesc characterCheckbox; + characterCheckbox.labelUtf8 = "Show character"; + characterCheckbox.info.userControlId = 0; + characterCheckbox.info.userControlType = ansel::kUserControlBoolean; + const bool defaultValue = true; + characterCheckbox.info.value = &defaultValue; + characterCheckbox.callback = [](const ansel::UserControlInfo& info) { + g_renderCustomUI = *reinterpret_cast<const bool*>(info.value); + }; + ansel::addUserControl(characterCheckbox); + ansel::setUserControlLabelLocalization(characterCheckbox.info.userControlId, "ru-RU", russianTranslationUtf8); + ansel::setUserControlLabelLocalization(characterCheckbox.info.userControlId, "es-ES", spanishTranslationUtf8); + ... +``` + 3. TAKING PICTURES WITH ANSEL ----------------------------- ### 3.1 ACTIVATING AND DEACTIVATING ANSEL |