diff --git a/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/02-ue.md b/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/02-ue.md index 2dec175910..c9be6e618f 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/02-ue.md +++ b/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/02-ue.md @@ -110,5 +110,6 @@ Arm ASR's behavior can be configured via the following plugin-specific console v |`r.ArmASR.ReactiveMaskForceReactiveMaterialValue` | 0 | 0, 1 | Force the reactive mask value for Reactive Shading Model materials, when > 0 this value can be used to override the value supplied in the Material Graph. | |`r.ArmASR.ReactiveMaskReactiveShadingModelID` | MSM_NUM | - | Treat the specified shading model as reactive, taking the CustomData0.x value as the reactive value to write into the mask. | +## Next steps You are now ready to use Arm ASR in your Unreal Engine projects. You can use [Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio) tools to measure the performance of your game as it runs on a mobile device, allowing you to monitor the effect of Arm ASR. diff --git a/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/04-generic_library.md b/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/04-generic_library.md index 894d6772b5..3351e154fb 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/04-generic_library.md +++ b/content/learning-paths/mobile-graphics-and-gaming/get-started-with-arm-asr/04-generic_library.md @@ -8,7 +8,7 @@ layout: learningpathall ## Introduction -Use the following steps to implement **Arm Accuracy Super Resolution (Arm ASR)** in your own custom engine. Arm ASR is an optimized version of [Fidelity Super Resolution 2](https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/main/docs/techniques/super-resolution-temporal.md) that has been heavily modified to include many mobile-oriented optimizations to make the technique suited for mobile. +Use the following steps to implement **Arm Accuracy Super Resolution (Arm ASR)** in your own custom engine. Arm ASR is an optimized version of [Fidelity Super Resolution 2](https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/main/docs/techniques/super-resolution-temporal.md) (FSR2) that has been heavily modified to include many mobile-oriented optimizations to make the technique suited for mobile. There are two ways you can integrate Arm ASR into your custom engine: @@ -56,49 +56,65 @@ To quickly integrate Arm ASR, which means the built-in standalone backend is use 2. Include the following header files in your codebase where you wish to interact with the technique: - - `$ARMASR_DIR/include/host/ffxm_fsr2.h#L1` - - `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h#L1` + - `$ARMASR_DIR/include/host/ffxm_fsr2.h` + - `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h` 3. Create a Vulkan backend. - - Allocate a Vulkan scratch buffer of the size returned by `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h#L65`. - - Create `FfxmDevice` via `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h#L65`. - - Create `FfxmInterface` by calling `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h#L99`. + - Allocate a Vulkan scratch buffer of the size returned by `ffxmGetScratchMemorySizeVK` in `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h`. + - Create `FfxmDevice` via `ffxmGetDeviceVK` in `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h`. + - Create `FfxmInterface` by calling `ffxmGetInterfaceVK` in `$ARMASR_DIR/include/host/backends/vk/ffxm_vk.h`. -4. Create a context by calling `ffxmFsr2ContextCreate` accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h#L296`. The parameters structure should be filled out matching the configuration of your application. +4. Create a context by calling `ffxmFsr2ContextCreate` in `$ARMASR_DIR/include/host/ffxm_fsr2.h`. The parameters structure should be filled out matching the configuration of your application. -5. Each frame call `ffxmFsr2ContextDispatch` via `$ARMASR_DIR/include/host/ffxm_fsr2.h#L337' to record/execute the technique's workloads. The parameters structure should be filled out matching the configuration of your application. +5. Each frame calls `ffxmFsr2ContextDispatch` via `$ARMASR_DIR/include/host/ffxm_fsr2.h` to record/execute the technique's workloads. The parameters structure should be filled out matching the configuration of your application. -6. When your application is terminating (or you wish to destroy the context for another reason) you should call `ffxmFsr2ContextDestroy` accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h#L360`. The GPU should be idle before calling this function. +6. When your application is terminating (or you wish to destroy the context for another reason) you should call `ffxmFsr2ContextDestroy` accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h`. The GPU should be idle before calling this function. -7. Sub-pixel jittering should be applied to your application's projection matrix. This should be done when performing the main rendering of your application. You should use the `ffxmFsr2GetJitterOffset` function accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h#L504` to compute the precise jitter offsets. +7. Sub-pixel jittering should be applied to your application's projection matrix. This should be done when performing the main rendering of your application. You should use the `ffxmFsr2GetJitterOffset` function accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h` to compute the precise jitter offsets. -8. A global mip bias should be applied when texturing. Applying a negative mipmap biasing will typically generate an upscaled image with better texture detail. We recommend applying the following formula to your Mipmap bias: +8. A global Mip bias should be applied when texturing. Applying a negative Mipmap biasing will typically generate an upscaled image with better texture detail. We recommend applying the following formula to your Mipmap bias: - ``` CPP + ``` cpp mipBias = log2(renderResolution/displayResolution) - 1.0; ``` -9. For the best upscaling quality it is strongly advised that you populate the Reactive mask according to our guidelines. You can also use `ffxmFsr2ContextGenerateReactiveMask` accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h#L348` as a starting point. +9. For the best upscaling quality it is strongly advised that you populate the Reactive mask according to our guidelines. You can also use `ffxmFsr2ContextGenerateReactiveMask` accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h` as a starting point. 10. Finally, link the two built libraries (**Arm_ASR_api** and **Arm_ASR_backend**). ## Tight integration -If you wish to use your own backend/renderer, a tight integration with your engine is required. For this, a similar process to the [quick integration](#quick-integration) described above is required, but with the added requirement to fill the `FfxmInterface` accessed via `$ARMASR_DIR/include/host/ffxm_interface.h#L438` with functions implemented on your end. +If you wish to use your own backend/renderer, a tight integration with your engine is required. For this, a similar process to the [quick integration](#quick-integration) described above is required, but with the added requirement to fill the `FfxmInterface` accessed via `$ARMASR_DIR/include/host/ffxm_interface.h` with functions implemented on your end. -In this approach the shaders are expected to be built by the engine. Arm ASR's shaders have been micro-optimized to use explicit 16-bit floating-point types so it is advisable that the shaders are built using such types (for example, `min16float` in hlsl or `float16_t` in glsl). For this you should define the symbols `#define FFXM_HLSL_6_2 1` and `#define FFXM_HALF 1` (FFXM_HALF is already defined in the provided shader sources) enabled with a value of `1`. +In this approach the shaders are expected to be built by the engine. Arm ASR's shaders have been micro-optimized to use explicit 16-bit floating-point types. It is therefore advisable that the shaders are built using such types. For example, `min16float` is used in High-level shader languag (HLSL) and `float16_t` in OpenGL Shading Language (GLSL). If you are using HLSL, define the following symbol with a value of `1`: -1. Include the `ffxm_interface.h` header file from `$ARMASR_DIR/include/host/ffxm_interface.h#L1` in your codebase. +```cpp +#define FFXM_HLSL_6_2 1 +``` + +The `FFXM_HALF` symbol is enabled by default in the provided shader sources. + +1. Include the following header in your codebase: -2. Implement your own functions (assume the names are `xxxGetInterfacexxx`, `xxxGetScratchMemorySizexxx`) and callbacks in `FfxmInterface` accessed via `$ARMASR_DIR/include/host/ffxm_interface.h#L438` to link Arm ASR with the engine's renderer. + - `$ARMASR_DIR/include/host/ffxm_interface.h` + +2. Implement your own functions (assume the names are `xxxGetInterfacexxx`, `xxxGetScratchMemorySizexxx`) and callbacks in `FfxmInterface` in `$ARMASR_DIR/include/host/ffxm_interface.h` to link Arm ASR with the engine's renderer. 3. Create your own backend by calling `xxxGetInterfacexxx`. A scratch buffer should be allocated of the size returned by calling `xxxGetScratchMemorySizexxx` and the pointer to that buffer passed to `xxxGetInterfacexxx`. 4. Now, you can follow the same steps from the quick integration instructions above, starting from step 4, creating an Arm ASR context. In the final step it is only necessary to link the **Arm_ASR_api** library. +## Integration Guidelines + +In the following section, additional details for integrating Arm ASR are listed. + +{{% notice %}} +The `FfxmFsr2ContextDescription` from `$ARMASR_DIR/include/host/ffxm_fsr2.h` is referenced multiple times throughout the Integration Guidelines. You should configure the `flags` field of this structure when modifying those bits, by setting the variables in `FfxmFsr2InitializationFlagBits`. +{{% /notice %}} + ### HLSL-based workflows -In an HLSL-based workflow using DirectX Shader Compiler to cross-compile to SPIRV do the following: +In an HLSL-based workflow using DirectX Shader Compiler to cross-compile to SPIR-V do the following: - Use the following flags when building: @@ -112,24 +128,22 @@ In an HLSL-based workflow using DirectX Shader Compiler to cross-compile to SPIR The Arm ASR API provides a set of shader quality presets, to select a version of the technique that balances quality and performance: -- **Quality** - This preset is an optimized version of FSR2 that maintains the same image quality as the original technique. +| Preset | Description | +|------------|-------------| +| **Quality** | An optimized version of FSR2 that maintains the same image quality as the original technique. | +| **Balanced** | Provides significant bandwidth savings and performance uplift while maintaining image quality close to the **Quality** preset. | +| **Performance** | A more aggressive preset that offers the highest performance with some quality sacrifices. | -- **Balanced** - This preset gives a significant improvement in both bandwidth savings and performance uplift while maintaining close image quality to the **Quality** preset. - -- **Performance** - This is a more aggressive preset that will give you the highest performance with some quality sacrifices. - -When creating a context, a `FfxmFsr2ShaderQualityMode` accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h#L119` needs to be provided as part of the input settings in `FfxmFsr2ContextDescription` `$ARMASR_DIR/include/host/ffxm_fsr2.h#L181`. +When creating a context, a `FfxmFsr2ShaderQualityMode` accessed via `$ARMASR_DIR/include/host/ffxm_fsr2.h` needs to be provided as part of the input settings in `FfxmFsr2ContextDescription`. ## Upscaling ratios To enhance flexibility when using the technique, developers can specify both a shader quality preset and an upscaling ratio. They can select any combination of **FfxmFsr2ShaderQualityMode** and **FfxmFsr2UpscalingRatio** according to their requirements to adjust the balance between quality and performance of the application. -We provide a couple of utilities to get the corresponding src resolution the frame should be using for rendering pre-upscaling based on the desired upscaling ratio `FfxmFsr2UpscalingRatio` ( `$ARMASR_DIR/include/host/ffxm_fsr2.h#L128`). -``` CPP +A couple of utilities are available to determine the source resolution the frame should use for rendering before upscaling. This calculation is based on the desired upscaling ratio, defined by `FfxmFsr2UpscalingRatio`. You can find this definition in `$ARMASR_DIR/include/host/ffxm_fsr2.h`. + +``` cpp float ffxmFsr2GetUpscaleRatioFactor(FfxmFsr2UpscalingRatio upscalingRatio) FfxErrorCode ffxmFsr2GetRenderResolutionFromUpscalingRatio( uint32_t* renderWidth, @@ -140,7 +154,7 @@ FfxErrorCode ffxmFsr2GetRenderResolutionFromUpscalingRatio( ``` ## Performance -Depending on your target hardware and operating configuration, Arm ASR will operate at different performance levels. +Depending on your target hardware and operating configuration, Arm ASR will operate at different performance levels. The table below compares the rendering performance of two Arm GPUs (Immortalis-G715 and Immortalis-G720) when using different upscaling settings at two target resolutions.