Skip to content

Commit 0ddca95

Browse files
rysrys
committed
FidelityFX CACAO v1.2
1 parent a582419 commit 0ddca95

29 files changed

+7960
-7953
lines changed

‎docs/FFX-CACAO-GUI.pdf

78.7 KB
Binary file not shown.

‎docs/FFX-CACAO-Technology.pdf

6.89 KB
Binary file not shown.

‎doxygen.conf

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
DOXYFILE_ENCODING = UTF-8
22
PROJECT_NAME = "FidelityFX CACAO"
33
OPTIMIZE_OUTPUT_FOR_C = YES
4-
INPUT = ffx-cacao/inc/ffx_cacao.h
4+
INPUT = ffx-cacao/inc/ffx_cacao.h ffx-cacao/inc/ffx_cacao_impl.h
55
OUTPUT_DIRECTORY = docs
66

77
ENABLE_PREPROCESSING = YES

‎ffx-cacao/inc/ffx_cacao.h

Lines changed: 129 additions & 265 deletions
Large diffs are not rendered by default.

‎ffx-cacao/inc/ffx_cacao_impl.h

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
// Modifications Copyright © 2021. Advanced Micro Devices, Inc. All Rights Reserved.
2+
3+
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
4+
// Copyright (c) 2016, Intel Corporation
5+
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
6+
// documentation files (the "Software"), to deal in the Software without restriction, including without limitation
7+
// the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
8+
// permit persons to whom the Software is furnished to do so, subject to the following conditions:
9+
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of
10+
// the Software.
11+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
12+
// THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
13+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
14+
// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
15+
// SOFTWARE.
16+
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
17+
// File changes (yyyy-mm-dd)
18+
// 2016-09-07: filip.strugar@intel.com: first commit
19+
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
20+
21+
/*! \file */
22+
23+
#pragma once
24+
25+
#include "ffx_cacao.h"
26+
27+
// #define FFX_CACAO_ENABLE_PROFILING
28+
// #define FFX_CACAO_ENABLE_D3D12
29+
// #define FFX_CACAO_ENABLE_VULKAN
30+
31+
#ifdef FFX_CACAO_ENABLE_D3D12
32+
#include <d3d12.h>
33+
#endif
34+
#ifdef FFX_CACAO_ENABLE_VULKAN
35+
#include <vulkan/vulkan.h>
36+
#endif
37+
38+
/**
39+
The return codes for the API functions.
40+
*/
41+
typedef enum FFX_CACAO_Status {
42+
FFX_CACAO_STATUS_OK = 0,
43+
FFX_CACAO_STATUS_INVALID_ARGUMENT = -1,
44+
FFX_CACAO_STATUS_INVALID_POINTER = -2,
45+
FFX_CACAO_STATUS_OUT_OF_MEMORY = -3,
46+
FFX_CACAO_STATUS_FAILED = -4,
47+
} FFX_CACAO_Status;
48+
49+
#ifdef FFX_CACAO_ENABLE_D3D12
50+
/**
51+
A struct containing all of the data used by FidelityFX-CACAO.
52+
A context corresponds to an ID3D12Device.
53+
*/
54+
typedef struct FFX_CACAO_D3D12Context FFX_CACAO_D3D12Context;
55+
56+
/**
57+
The parameters for creating a context.
58+
*/
59+
typedef struct FFX_CACAO_D3D12ScreenSizeInfo {
60+
uint32_t width; ///< width of the input/output buffers
61+
uint32_t height; ///< height of the input/output buffers
62+
ID3D12Resource *depthBufferResource; ///< pointer to depth buffer ID3D12Resource
63+
D3D12_SHADER_RESOURCE_VIEW_DESC depthBufferSrvDesc; ///< depth buffer D3D12_SHADER_RESOURCE_VIEW_DESC
64+
ID3D12Resource *normalBufferResource; ///< optional pointer to normal buffer ID3D12Resource (leave as NULL if none is provided)
65+
D3D12_SHADER_RESOURCE_VIEW_DESC normalBufferSrvDesc; ///< normal buffer D3D12_SHADER_RESOURCE_VIEW_DESC
66+
ID3D12Resource *outputResource; ///< pointer to output buffer ID3D12Resource
67+
D3D12_UNORDERED_ACCESS_VIEW_DESC outputUavDesc; ///< output buffer D3D12_UNORDERED_ACCESS_VIEW_DESC
68+
FFX_CACAO_Bool useDownsampledSsao; ///< Whether SSAO should be generated at native resolution or half resolution. It is recommended to enable this setting for improved performance.
69+
} FFX_CACAO_D3D12ScreenSizeInfo;
70+
#endif
71+
72+
#ifdef FFX_CACAO_ENABLE_VULKAN
73+
/**
74+
A struct containing all of the data used by FidelityFX-CACAO.
75+
A context corresponds to a VkDevice.
76+
*/
77+
typedef struct FFX_CACAO_VkContext FFX_CACAO_VkContext;
78+
79+
/**
80+
Miscellaneous flags for used for Vulkan context creation by FidelityFX-CACAO
81+
*/
82+
typedef enum FFX_CACAO_VkCreateFlagsBits {
83+
FFX_CACAO_VK_CREATE_USE_16_BIT = 0x00000001, ///< Flag controlling whether 16-bit optimisations are enabled in shaders.
84+
FFX_CACAO_VK_CREATE_USE_DEBUG_MARKERS = 0x00000002, ///< Flag controlling whether debug markers should be used.
85+
FFX_CACAO_VK_CREATE_NAME_OBJECTS = 0x00000004, ///< Flag controlling whether Vulkan objects should be named.
86+
} FFX_CACAO_VkCreateFlagsBits;
87+
typedef uint32_t FFX_CACAO_VkCreateFlags;
88+
89+
/**
90+
The parameters for creating a context.
91+
*/
92+
typedef struct FFX_CACAO_VkCreateInfo {
93+
VkPhysicalDevice physicalDevice; ///< The VkPhysicalDevice corresponding to the VkDevice in use
94+
VkDevice device; ///< The VkDevice to use FFX CACAO with
95+
FFX_CACAO_VkCreateFlags flags; ///< Miscellaneous flags for context creation
96+
} FFX_CACAO_VkCreateInfo;
97+
98+
/**
99+
The parameters necessary when changing the screen size of FidelityFX CACAO.
100+
*/
101+
typedef struct FFX_CACAO_VkScreenSizeInfo {
102+
uint32_t width; ///< width of the input/output buffers
103+
uint32_t height; ///< height of the input/output buffers
104+
VkImageView depthView; ///< An image view for the depth buffer, should be in layout VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL when used with FFX CACAO
105+
VkImageView normalsView; ///< An optional image view for the normal buffer (may be VK_NULL_HANDLE). Should be in layout VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL when used with FFX CACAO
106+
VkImage output; ///< An image for writing output from FFX CACAO, must have the same dimensions as the input
107+
VkImageView outputView; ///< An image view corresponding to the output image.
108+
FFX_CACAO_Bool useDownsampledSsao; ///< Whether SSAO should be generated at native resolution or half resolution. It is recommended to enable this setting for improved performance.
109+
} FFX_CACAO_VkScreenSizeInfo;
110+
#endif
111+
112+
#ifdef FFX_CACAO_ENABLE_PROFILING
113+
/**
114+
A timestamp. The label gives the name of the stage of the effect, and the ticks is the number of GPU ticks spent on that stage.
115+
*/
116+
typedef struct FFX_CACAO_Timestamp {
117+
const char *label; ///< name of timestamp stage
118+
uint64_t ticks; ///< number of GPU ticks taken for stage
119+
} FFX_CACAO_Timestamp;
120+
121+
/**
122+
An array of timestamps for detailed profiling information. The array timestamps contains numTimestamps entries.
123+
Entry 0 of the timestamps array is guaranteed to be the total time taken by the effect.
124+
*/
125+
typedef struct FFX_CACAO_DetailedTiming {
126+
uint32_t numTimestamps; ///< number of timetstamps in the array timestamps
127+
FFX_CACAO_Timestamp timestamps[32]; ///< array of timestamps for each FFX CACAO stage
128+
} FFX_CACAO_DetailedTiming;
129+
#endif
130+
131+
#ifdef __cplusplus
132+
extern "C"
133+
{
134+
#endif
135+
136+
#ifdef FFX_CACAO_ENABLE_D3D12
137+
/**
138+
Gets the size in bytes required by a context. This is to be used to allocate space for the context.
139+
For example:
140+
141+
\code{.cpp}
142+
size_t FFX_CACAO_D3D12ContextSize = ffxCacaoD3D12GetContextSize();
143+
FFX_CACAO_D3D12Context *context = (FFX_CACAO_D3D12Context*)malloc(FFX_CACAO_D3D12GetContextSize);
144+
145+
// ...
146+
147+
FFX_CACAO_D3D12DestroyContext(context);
148+
free(context);
149+
\endcode
150+
151+
\return The size in bytes of an FFX_CACAO_D3D12Context.
152+
*/
153+
size_t FFX_CACAO_D3D12GetContextSize();
154+
155+
/**
156+
Initialises an FFX_CACAO_D3D12Context.
157+
158+
\param context A pointer to the context to initialise.
159+
\param device A pointer to the D3D12 device.
160+
\return The corresponding error code.
161+
*/
162+
FFX_CACAO_Status FFX_CACAO_D3D12InitContext(FFX_CACAO_D3D12Context* context, ID3D12Device* device);
163+
164+
/**
165+
Destroys an FFX_CACAO_D3D12Context.
166+
167+
\param context A pointer to the context to be destroyed.
168+
\return The corresponding error code.
169+
170+
\note This function does not destroy screen size dependent resources, and must be called after FFX_CACAO_D3D12DestroyScreenSizeDependentResources.
171+
*/
172+
FFX_CACAO_Status FFX_CACAO_D3D12DestroyContext(FFX_CACAO_D3D12Context* context);
173+
174+
/**
175+
Initialises screen size dependent resources for the FFX_CACAO_D3D12Context.
176+
177+
\param context A pointer to the FFX_CACAO_D3D12Context.
178+
\param info A pointer to an FFX_CACAO_D3D12ScreenSizeInfo struct containing screen size info.
179+
\return The corresponding error code.
180+
*/
181+
FFX_CACAO_Status FFX_CACAO_D3D12InitScreenSizeDependentResources(FFX_CACAO_D3D12Context* context, const FFX_CACAO_D3D12ScreenSizeInfo* info);
182+
183+
/**
184+
Destroys screen size dependent resources for the FFX_CACAO_D3D12Context.
185+
186+
\param context A pointer to the FFX_CACAO_D3D12Context.
187+
\return The corresponding error code.
188+
*/
189+
FFX_CACAO_Status FFX_CACAO_D3D12DestroyScreenSizeDependentResources(FFX_CACAO_D3D12Context* context);
190+
191+
/**
192+
Update the settings of the FFX_CACAO_D3D12Context to those stored in the FFX_CACAO_Settings struct.
193+
194+
\param context A pointer to the FFX_CACAO_D3D12Context to update.
195+
\param settings A pointer to the FFX_CACAO_Settings struct containing the new settings.
196+
\return The corresponding error code.
197+
*/
198+
FFX_CACAO_Status FFX_CACAO_D3D12UpdateSettings(FFX_CACAO_D3D12Context* context, const FFX_CACAO_Settings* settings);
199+
200+
/**
201+
Append commands for drawing FFX CACAO to the provided ID3D12GraphicsCommandList.
202+
203+
\param context A pointer to the FFX_CACAO_D3D12Context.
204+
\param commandList A pointer to the ID3D12GraphicsCommandList to append commands to.
205+
\param proj A pointer to the projection matrix.
206+
\param normalsToView An optional pointer to a matrix for transforming normals to in the normal buffer to viewspace.
207+
\return The corresponding error code.
208+
*/
209+
FFX_CACAO_Status FFX_CACAO_D3D12Draw(FFX_CACAO_D3D12Context* context, ID3D12GraphicsCommandList* commandList, const FFX_CACAO_Matrix4x4* proj, const FFX_CACAO_Matrix4x4* normalsToView);
210+
211+
#if FFX_CACAO_ENABLE_PROFILING
212+
/**
213+
Get detailed performance timings from the previous frame.
214+
215+
\param context A pointer to the FFX_CACAO_D3D12Context.
216+
\param timings A pointer to an FFX_CACAO_DetailedTiming struct to fill in with detailed timings.
217+
\result The corresponding error code.
218+
*/
219+
FFX_CACAO_Status FFX_CACAO_D3D12GetDetailedTimings(FFX_CACAO_D3D12Context* context, FFX_CACAO_DetailedTiming* timings);
220+
#endif
221+
#endif
222+
223+
#ifdef FFX_CACAO_ENABLE_VULKAN
224+
/**
225+
Gets the size in bytes required by a Vulkan context. This is to be used to allocate space for the context.
226+
For example:
227+
228+
\code{.cpp}
229+
size_t FFX_CACAO_VkContextSize = ffxCacaoVkGetContextSize();
230+
FFX_CACAO_VkContext *context = (FFX_CACAO_VkContext*)malloc(FFX_CACAO_VkGetContextSize);
231+
232+
// ...
233+
234+
FFX_CACAO_VkDestroyContext(context);
235+
free(context);
236+
\endcode
237+
238+
\return The size in bytes of an FFX_CACAO_VkContext.
239+
*/
240+
size_t FFX_CACAO_VkGetContextSize();
241+
242+
/**
243+
Initialises an FFX_CACAO_VkContext.
244+
245+
\param context A pointer to the context to initialise.
246+
\param info A pointer to an FFX_CACAO_VkCreateInfo struct with parameters such as the vulkan device.
247+
\return The corresponding error code.
248+
*/
249+
FFX_CACAO_Status FFX_CACAO_VkInitContext(FFX_CACAO_VkContext* context, const FFX_CACAO_VkCreateInfo *info);
250+
251+
/**
252+
Destroys an FFX_CACAO_VkContext.
253+
254+
\param context A pointer to the context to be destroyed.
255+
\return The corresponding error code.
256+
257+
\note This function does not destroy screen size dependent resources, and must be called after FFX_CACAO_VkDestroyScreenSizeDependentResources.
258+
*/
259+
FFX_CACAO_Status FFX_CACAO_VkDestroyContext(FFX_CACAO_VkContext* context);
260+
261+
/**
262+
Initialises screen size dependent resources for the FFX_CACAO_VkContext.
263+
264+
\param context A pointer to the FFX_CACAO_VkContext.
265+
\param info A pointer to an FFX_CACAO_VkScreenSizeInfo struct containing screen size info.
266+
\return The corresponding error code.
267+
*/
268+
FFX_CACAO_Status FFX_CACAO_VkInitScreenSizeDependentResources(FFX_CACAO_VkContext* context, const FFX_CACAO_VkScreenSizeInfo* info);
269+
270+
/**
271+
Destroys screen size dependent resources for the FFX_CACAO_VkContext.
272+
273+
\param context A pointer to the FFX_CACAO_VkContext.
274+
\return The corresponding error code.
275+
*/
276+
FFX_CACAO_Status FFX_CACAO_VkDestroyScreenSizeDependentResources(FFX_CACAO_VkContext* context);
277+
278+
/**
279+
Update the settings of the FFX_CACAO_VkContext to those stored in the FFX_CACAO_Settings struct.
280+
281+
\param context A pointer to the FFX_CACAO_VkContext to update.
282+
\param settings A pointer to the FFX_CACAO_Settings struct containing the new settings.
283+
\return The corresponding error code.
284+
*/
285+
FFX_CACAO_Status FFX_CACAO_VkUpdateSettings(FFX_CACAO_VkContext* context, const FFX_CACAO_Settings* settings);
286+
287+
/**
288+
Append commands for drawing FFX CACAO to the provided VkCommandBuffer.
289+
290+
\param context A pointer to the FFX_CACAO_VkContext.
291+
\param commandList The VkCommandBuffer to append commands to.
292+
\param proj A pointer to the projection matrix.
293+
\param normalsToView An optional pointer to a matrix for transforming normals to in the normal buffer to viewspace.
294+
\return The corresponding error code.
295+
*/
296+
FFX_CACAO_Status FFX_CACAO_VkDraw(FFX_CACAO_VkContext* context, VkCommandBuffer commandList, const FFX_CACAO_Matrix4x4* proj, const FFX_CACAO_Matrix4x4* normalsToView);
297+
298+
#ifdef FFX_CACAO_ENABLE_PROFILING
299+
/**
300+
Get detailed performance timings from the previous frame.
301+
302+
\param context A pointer to the FFX_CACAO_VkContext.
303+
\param timings A pointer to an FFX_CACAO_DetailedTiming struct to fill in with detailed timings.
304+
\result The corresponding error code.
305+
*/
306+
FFX_CACAO_Status FFX_CACAO_VkGetDetailedTimings(FFX_CACAO_VkContext* context, FFX_CACAO_DetailedTiming* timings);
307+
#endif
308+
#endif
309+
310+
#ifdef __cplusplus
311+
}
312+
#endif

‎ffx-cacao/readme.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,27 @@ The **FidelityFX CACAO** library implements screen space ambient occlusion for u
44

55
# Project Integration
66

7-
FidelityFX CACAO supports three compile time options. These are:
7+
FidelityFX CACAO comes with two main header files, `ffx-cacao/inc/ffx_cacao.h` and `ffx-cacao/inc/ffx_cacao_impl.h`. The file `ffx-cacao/inc/ffx_cacao.h` contains reusable C++ functions and struct definitions for integration of FidelityFX CACAO into custom engines. The functions declared in this header file are defined in `ffx-cacao/src/ffx_cacao.cpp`. The header file `ffx-cacao/inc/ffx_cacao_impl.h` is for use in quick integration of FidelityFX CACAO into DX12 and Vulkan engines. The functions declared in this file are defined in `ffx-cacao/src/ffx_cacao_impl.cpp`, which serves as a reference implementation of FidelityFX CACAO.
8+
9+
# Reusable Functions and Structs
10+
11+
The reusable functions and structs provided in `ffx-cacao/src/ffx_cacao.h` are documented via doxygen comments in the header file itself. The functions and structs are used to initialise the constant buffers used by FidelityFX CACAO from a user friendly settings struct `FFX_CACAO_Settings`.
12+
13+
# Reference Implementation
14+
15+
The reference implementation of FidelityFX CACAO supports three compile time options. These are:
816

917
```C++
1018
FFX_CACAO_ENABLE_D3D12
1119
FFX_CACAO_ENABLE_VK
1220
FFX_CACAO_ENABLE_PROFILING
1321
```
1422

15-
For use with D3D12 or Vulkan, the symbols `FFX_CACAO_ENABLE_D3D12` or `FFX_CACAO_ENABLE_VK` must be defined. If you wish to get detailed timings from FFX CACAO the symbol `FFX_CACAO_ENABLE_PROFILING` must be defined. These symbols can either be defined in the header `ffx-cacao/inc/ffx_cacao.h` itself by uncommenting the respective definitions, or they can defined in compiler flags. The provided sample of FFX CACAO defines these symbols using compiler flags.
23+
For use with D3D12 or Vulkan, the symbols `FFX_CACAO_ENABLE_D3D12` or `FFX_CACAO_ENABLE_VK` must be defined. If you wish to get detailed timings from FFX CACAO the symbol `FFX_CACAO_ENABLE_PROFILING` must be defined. These symbols can either be defined in the header `ffx-cacao/inc/ffx_cacao_impl.h` itself by uncommenting the respective definitions, or they can defined in compiler flags. The provided sample of FFX CACAO defines these symbols using compiler flags.
1624

1725
# Context Initialisation and Shutdown
1826

19-
First the FFX CACAO header must be included. This can be found at `ffx-cacao/inc/ffx_cacao.h`. Then a context must be created. This is usually done only once per device. To create a context you must first query for the size of a context, allocate space for a context, then inintialise the context.
27+
First the FFX CACAO header must be included. This can be found at `ffx-cacao/inc/ffx_cacao_impl.h`. Then a context must be created. This is usually done only once per device. To create a context you must first query for the size of a context, allocate space for a context, then inintialise the context.
2028

2129

2230
For D3D12 the initialisation and shutdown processes are as follows:

0 commit comments

Comments
 (0)