Updating Ansel SDK to v1.6

3 files changed, 47 insertions, 14 deletions

diff --git a/docs/Ansel_integration_guide.html b/docs/Ansel_integration_guide.html
index c9f2bbf..656e293 100644
--- a/docs/Ansel_integration_guide.html
+++ b/docs/Ansel_integration_guide.html
@@ -163,7 +163,7 @@ config.stopCaptureCallback = stopAnselCaptureCallback;
         <span class="pl-c"><span class="pl-c">//</span> the SDK is actually loaded</span>

         <span class="pl-c1">kSetConfigurationSdkNotLoaded</span>

     };</pre></div>

-<p>The integration should only continue as normal (with regard to the Ansel functionality at least) when <code>kSetConfigurationSuccess</code> is returned. In case <code>kSetConfigurationIncompatibleVersion</code> is returned, most likely the Ansel SDK binary was obtained without updating the headers, which also contain a version. Every update of the Ansel SDK requires a new build of a game. In case <code>kSetConfigurationIncorrectConfiguration</code> is returned, on of the following fields could be set incorrectly:</p>

+<p>The integration should only continue as normal (with regard to the Ansel functionality at least) when <code>kSetConfigurationSuccess</code> is returned. In case <code>kSetConfigurationIncompatibleVersion</code> is returned, most likely the Ansel SDK binary was obtained without updating the headers, which also contain a version. Every update of the Ansel SDK requires a new build of a game. In case <code>kSetConfigurationIncorrectConfiguration</code> is returned, one of the following fields could be set incorrectly:</p>

 <ul>

 <li>

 <code>right</code>, <code>up</code>, <code>forward</code> vectors do not form an orthogonal basis</li>

@@ -173,9 +173,9 @@ config.stopCaptureCallback = stopAnselCaptureCallback;
 <li>

 <code>fovType</code> is neither horizontal, nor vertical</li>

 <li>

-<code>gameWindowHandle</code> field is not set

-In case <code>kSetConfigurationSdkNotLoaded</code> is returned, the reason is that the Ansel SDK is delay loaded and <code>setConfiguration</code> is called before loading the library via <code>loadAnselSDKLibrary</code> (see code under samples folder).</li>

+<code>gameWindowHandle</code> field is not set</li>

 </ul>

+<p>In case <code>kSetConfigurationSdkNotLoaded</code> is returned, the reason is that the Ansel SDK is delay loaded and <code>setConfiguration</code> is called before loading the library via <code>loadAnselSDKLibrary</code> (see code under samples folder).</p>

 <h3>

 <a id="user-content-22-session" class="anchor" href="#22-session" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>2.2 SESSION</h3>

 <p>The time period from when a player successfully starts Ansel and until Ansel is stopped is called a session. A session is collaboratively started and operated between the game and Ansel. When a player requests a session start (for example by pressing ALT+F2) Ansel will call the registered session start callback. It is however expected that Ansel cannot always be activated. The game may for instance be on a loading screen or playing a movie sequence. The callback should then immediately return with <code>Ansel::kDisallowed</code> return value.</p>

@@ -404,7 +404,7 @@ ANSEL_SDK_API <span class="pl-k">void</span> <span class="pl-en">rotationMatrixV
 <h3>

 <a id="user-content-25-user-controls" class="anchor" href="#25-user-controls" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>2.5 USER CONTROLS</h3>

 <p>Sometimes a game developer is willing to expose some of the game properties in the Ansel UI. One example of this could be 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.</p>

-<p><a href="ImageUserControls.jpg" target="_blank"><img src="ImageUserControls.jpg" alt="User controls example" style="max-width:100%;"></a>{width=25% height=25%}</p>

+<p><a href="ImageUserControls.jpg" target="_blank" rel="noopener noreferrer"><img src="ImageUserControls.jpg" alt="User controls example" style="max-width:100%;"></a></p>

 <p>The basics of the API look like this:</p>

 <div class="highlight highlight-source-c++"><pre>  <span class="pl-c"><span class="pl-c">//</span> This function adds a user control defined with the UserControlDesc object</span>

   ANSEL_SDK_API UserControlStatus <span class="pl-en">addUserControl</span>(<span class="pl-k">const</span> UserControlDesc&amp; desc);

@@ -466,6 +466,21 @@ ansel::StartSessionStatus <span class="pl-en">startAnselSessionCallback</span>(
     ....

 }

 </pre></div>

+<h3>

+<a id="user-content-26-high-quality-captures" class="anchor" href="#26-high-quality-captures" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>2.6 HIGH QUALITY CAPTURES</h3>

+<p>Ansel exposes an optional callback function and configuration fields for the application to switch to a high-quality rendering mode, allowing users to easily take pictures with better quality than they would be able to realistically use in actual gameplay.  The configuration now contains a field for this callback:</p>

+<pre><code>configuration.changeQualityCallback = changeAnselQualityCallback;

+</code></pre>

+<p><code>changeQualityCallback</code> is an application-provided callback function that Ansel will call when it wants to change the quality level (either to raise it or lower it).  When the feature is enabled in on the driver side, Ansel will call <code>changeQualityCallback(true)</code> when it detects that the camera has stopped moving, and <code>changeQualityCallback(false)</code> when it detects that the camera has started moving again.  This way, the user is able to position the camera smoothly and only suffers the performance penalty of higher quality rendering when the camera is positioned for the shot.</p>

+<p>The application can choose to interpret "high quality" however it wants in the <code>changeQualityCallback</code>.  The simplest approach would be to turn all in-game settings to the highest possible values.  Alternatively or in addition, the application could individually tweak specific rendering options, such as...</p>

+<ul>

+<li>Increasing texture resolution/quality</li>

+<li>For games with ray tracing, shooting more rays per effect</li>

+<li>Increasing shadow map resolution</li>

+<li>Increasing tessellation factors</li>

+<li>Increasing draw distance</li>

+<li>Increasing particle counts</li>

+</ul>

 <h2>

 <a id="user-content-3-taking-pictures-with-ansel" class="anchor" href="#3-taking-pictures-with-ansel" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>3. TAKING PICTURES WITH ANSEL</h2>

 <h3>

@@ -499,7 +514,7 @@ ansel::StartSessionStatus <span class="pl-en">startAnselSessionCallback</span>(
 <a id="user-content-4-troubleshooting-and-debugging-common-problems" class="anchor" href="#4-troubleshooting-and-debugging-common-problems" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>4. TROUBLESHOOTING AND DEBUGGING COMMON PROBLEMS</h2>

 <p>In this section we collected commonly occurring problems we've seen while integrating Ansel with games. This section can hopefully help you resolve a problem or two. It is generally useful to be able to inspect the individual shot tiles that are captured when generating pictures that require multiple shots. Locate the <code>NvCameraConfiguration.exe</code> utility. It can be found inside</p>

 <p>Run the utility. A screen similar to this one should appear:</p>

-<p><a href="NvCameraConfiguration.exe_screen.png" target="_blank"><img src="NvCameraConfiguration.exe_screen.png" alt="NvCameraConfiguration utility" style="max-width:100%;"></a>{width=60% height=60%}</p>

+<p><a href="NvCameraConfiguration.exe_screen.png" target="_blank" rel="noopener noreferrer"><img src="NvCameraConfiguration.exe_screen.png" alt="NvCameraConfiguration utility" style="max-width:100%;"></a>{width=60% height=60%}</p>

 <p>Check the 'Keep Intermediate Shots' option so that you can inspect the individual tiles. You can also pick a different location to store the tiles by changing the 'Temp Directory for Intermediate Shots'.</p>

 <p>Notice the 'Log level' setting. By default this is set to 'Disabled', which means that no logs are produced. If you set this to for instance 'Info' then all log messages with severity Info and higher will be emitted to a log file. Log files are stored in the current users profile directory, inside an 'ansel' folder. The path is <code>%USERPROFILE%\ansel</code>.  Each log file is named after the associated executable and includes a timestamp. Please note that multiple log files can be produced by the same game during one session since each device starts a separate Ansel logging session. That being said only one device (and therefore log file) will be associated with the presentable surface and will thus contain the most helpful information.</p>

 <h3>

@@ -519,31 +534,31 @@ ansel::StartSessionStatus <span class="pl-en">startAnselSessionCallback</span>(
 <h4>

 <a id="user-content-421-image-tiles-suffer-from-acne" class="anchor" href="#421-image-tiles-suffer-from-acne" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>4.2.1 Image tiles suffer from "acne"</h4>

 <p>This is probably best described with images. Here is a tile exhibiting the problem:</p>

-<p><a href="ImageAcne.jpg" target="_blank"><img src="ImageAcne.jpg" alt="Image acne" style="max-width:100%;"></a></p>

+<p><a href="ImageAcne.jpg" target="_blank" rel="noopener noreferrer"><img src="ImageAcne.jpg" alt="Image acne" style="max-width:100%;"></a></p>

 <p>Note the "acne" to the left of the tree, caused by temporal anti-aliasing. This can be fixed in two different ways. One method is to use the <code>captureSettleLatency</code> field in the configuration object. This field specifies how many frames Ansel should wait when taking multipart shots for the frame to settle - i.e. for any temporal effects to have settled. In this specific case (where the image is taken from) it takes one frame so the value should be 1. This is what the image looks like with that setting:</p>

-<p><a href="ImageWithoutAcne.jpg" target="_blank"><img src="ImageWithoutAcne.jpg" alt="Image without acne" style="max-width:100%;"></a></p>

+<p><a href="ImageWithoutAcne.jpg" target="_blank" rel="noopener noreferrer"><img src="ImageWithoutAcne.jpg" alt="Image without acne" style="max-width:100%;"></a></p>

 <p>Another way to solve this problem is to harness the <code>startCapture</code>/<code>stopCapture</code> callbacks to disable temporal AA. This effectively disables the temporal AA feature during the multipart capture sequence.

 Which solution should you use?  Well, it depends. You need to subjectively evaluate how much the temporal AA enhances image quality vs the cost of waiting for the frame to settle. At a <code>captureSettleLatency</code> of 1 the cost is rather small and thus weighs in favor of using that solution.</p>

 <h4>

 <a id="user-content-422-ghosting-everywhere-in-final-picture" class="anchor" href="#422-ghosting-everywhere-in-final-picture" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>4.2.2 Ghosting everywhere in final picture</h4>

 <p>Usually it looks something like this:</p>

-<p><a href="GhostingEverywhere.jpg" target="_blank"><img src="GhostingEverywhere.jpg" alt="Ghosting everywhere" style="max-width:100%;"></a></p>

+<p><a href="GhostingEverywhere.jpg" target="_blank" rel="noopener noreferrer"><img src="GhostingEverywhere.jpg" alt="Ghosting everywhere" style="max-width:100%;"></a></p>

 <p>Most often this is the result of incorrect field of view being submitted to Ansel - or error made on conversion or usage of value coming back from Ansel. It is recommended that you match the field of view type between game and Ansel to avoid any conversion mistakes. See section 2.1 on how you can configure Ansel to use the game's field of view.</p>

 <h4>

 <a id="user-content-423-screen-space-reflections-fade-out-with-increased-highres-capture-resolution" class="anchor" href="#423-screen-space-reflections-fade-out-with-increased-highres-capture-resolution" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>4.2.3 Screen space reflections fade out with increased Highres capture resolution</h4>

 <p>Below is a regular screenshot taken with Ansel:</p>

-<p><a href="ScreenSpaceReflections.jpg" target="_blank"><img src="ScreenSpaceReflections.jpg" alt="Screen space reflections" style="max-width:100%;"></a></p>

+<p><a href="ScreenSpaceReflections.jpg" target="_blank" rel="noopener noreferrer"><img src="ScreenSpaceReflections.jpg" alt="Screen space reflections" style="max-width:100%;"></a></p>

 <p>If we now select capture type Highres with a large enough multiplier we get this picture (scaled down in resolution to fit this document):</p>

-<p><a href="ScreenSpaceReflectionsReduced.jpg" target="_blank"><img src="ScreenSpaceReflectionsReduced.jpg" alt="Screen space reflections reduced" style="max-width:100%;"></a></p>

+<p><a href="ScreenSpaceReflectionsReduced.jpg" target="_blank" rel="noopener noreferrer"><img src="ScreenSpaceReflectionsReduced.jpg" alt="Screen space reflections reduced" style="max-width:100%;"></a></p>

 <p>There is unfortunately no workaround for this problem, it is a limitation of the capture method used.</p>

 <h4>

 <a id="user-content-424-its-all-a-blur" class="anchor" href="#424-its-all-a-blur" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>4.2.4 It's all a blur</h4>

 <p>Motion blur needs to be disabled during multipart capture. Otherwise results like this can be produced when taking 360 picture:</p>

-<p><a href="Blur.jpg" target="_blank"><img src="Blur.jpg" alt="Blurry capture" style="max-width:100%;"></a></p>

+<p><a href="Blur.jpg" target="_blank" rel="noopener noreferrer"><img src="Blur.jpg" alt="Blurry capture" style="max-width:100%;"></a></p>

 <h4>

 <a id="user-content-425-streaky-reflections" class="anchor" href="#425-streaky-reflections" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>4.2.5 Streaky reflections</h4>

 <p>When enabling highres capture for your game you may witness results similar to this:</p>

-<p><a href="StreakyReflections.jpg" target="_blank"><img src="StreakyReflections.jpg" alt="Streaky reflections in capture" style="max-width:100%;"></a></p>

+<p><a href="StreakyReflections.jpg" target="_blank" rel="noopener noreferrer"><img src="StreakyReflections.jpg" alt="Streaky reflections in capture" style="max-width:100%;"></a></p>

 <p>The reason may be that the projection offset and reduced field of view employed by the highres capture method is not being accounted for in the game's reflection code path.</p>

 <h3>

 <a id="user-content-43-the-view-of-the-world-pops-when-entering-and-exiting-ansel-mode" class="anchor" href="#43-the-view-of-the-world-pops-when-entering-and-exiting-ansel-mode" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>4.3 THE VIEW OF THE WORLD "POPS" WHEN ENTERING AND EXITING ANSEL MODE</h3>

diff --git a/docs/Ansel_integration_guide.md b/docs/Ansel_integration_guide.md
index 3c5b30a..8cca8eb 100644
--- a/docs/Ansel_integration_guide.md
+++ b/docs/Ansel_integration_guide.md
@@ -137,12 +137,13 @@ The `ansel::setConfiguration` function returns its status. The possible return v
     };

 ```

 

-The integration should only continue as normal (with regard to the Ansel functionality at least) when `kSetConfigurationSuccess` is returned. In case `kSetConfigurationIncompatibleVersion` is returned, most likely the Ansel SDK binary was obtained without updating the headers, which also contain a version. Every update of the Ansel SDK requires a new build of a game. In case `kSetConfigurationIncorrectConfiguration` is returned, on of the following fields could be set incorrectly:

+The integration should only continue as normal (with regard to the Ansel functionality at least) when `kSetConfigurationSuccess` is returned. In case `kSetConfigurationIncompatibleVersion` is returned, most likely the Ansel SDK binary was obtained without updating the headers, which also contain a version. Every update of the Ansel SDK requires a new build of a game. In case `kSetConfigurationIncorrectConfiguration` is returned, one of the following fields could be set incorrectly:

 * `right`, `up`, `forward` vectors do not form an orthogonal basis

 * `startSessionCallback` or `stopSessionCallback` is nullptr

 * 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).

 

 ### 2.2 SESSION

@@ -414,7 +415,7 @@ To identify the HDR buffer for Ansel call `markBufferBind` before binding the bu
 ### 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 be 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.

 

-![User controls example](ImageUserControls.jpg){width=25% height=25%}

+![User controls example](ImageUserControls.jpg)

 

 The basics of the API look like this:

 

@@ -490,6 +491,23 @@ ansel::StartSessionStatus startAnselSessionCallback(
 

 ```

 

+### 2.6 HIGH QUALITY CAPTURES

+Ansel exposes an optional callback function and configuration fields for the application to switch to a high-quality rendering mode, allowing users to easily take pictures with better quality than they would be able to realistically use in actual gameplay.  The configuration now contains a field for this callback:

+

+```

+configuration.changeQualityCallback = changeAnselQualityCallback;

+```

+

+`changeQualityCallback` is an application-provided callback function that Ansel will call when it wants to change the quality level (either to raise it or lower it).  When the feature is enabled in on the driver side, Ansel will call `changeQualityCallback(true)` when it detects that the camera has stopped moving, and `changeQualityCallback(false)` when it detects that the camera has started moving again.  This way, the user is able to position the camera smoothly and only suffers the performance penalty of higher quality rendering when the camera is positioned for the shot.

+

+The application can choose to interpret "high quality" however it wants in the `changeQualityCallback`.  The simplest approach would be to turn all in-game settings to the highest possible values.  Alternatively or in addition, the application could individually tweak specific rendering options, such as...

+* Increasing texture resolution/quality

+* For games with ray tracing, shooting more rays per effect

+* Increasing shadow map resolution

+* Increasing tessellation factors

+* Increasing draw distance

+* Increasing particle counts

+

 ## 3. TAKING PICTURES WITH ANSEL

 

 ### 3.1 ACTIVATING AND DEACTIVATING ANSEL

diff --git a/docs/Ansel_integration_guide.pdf b/docs/Ansel_integration_guide.pdf
index 7001500..829d7a9 100644
--- a/docs/Ansel_integration_guide.pdf
+++ b/docs/Ansel_integration_guide.pdf