FidelityFX Brixelizer 1.0

// =============================================================================
// Initialize/destroy the FFX Brixelizer backend
// =============================================================================

FfxBrixelizerContextDescription  desc = {};

desc.sdfCenter    = ...;                        // The point in world space around which to center the cascades.
desc.numCascades  = ...;                        // The number of cascades managed by the Brixelizer simple context.
desc.flags        = ...;                        // Flags for context creation. See <c><i>FfxBrixelizerContextFlags</i></c>.

uint32_t numCascadeResources = 0;
for (uint32_t i = 0; i < desc.numCascades ; ++i) {
    FfxBrixelizerCascadeDescription  *cascadeDesc = &cascadeDescs[i];
    cascadeDesc->flags      = ...;                              // Flags for cascade creation. See <c><i>FfxBrixelizerCascadeFlag</i></c>.
    cascadeDesc->voxelSize  = ...;                              // The edge size of voxels in world space for the cascade.
    switch (cascadeDesc->flags  & (FFX_BRIXELIZER_CASCADE_STATIC  | FFX_BRIXELIZER_CASCADE_DYNAMIC )) {
    case FFX_BRIXELIZER_CASCADE_STATIC :
    case FFX_BRIXELIZER_CASCADE_DYNAMIC :
        ++numCascadeResources;
        break;
    case (FFX_BRIXELIZER_CASCADE_STATIC  | FFX_BRIXELIZER_CASCADE_DYNAMIC ):
        numCascadeResources += 3;
        break;
    default:
        assert(false);
    }
}

desc.backendInterface  = ffxGetInterface (...); // An implementation of the FidelityFX backend for use with Brixelizer.

FfxBrixelizerContext  context = {};
FfxErrorCode  error = ffxBrixelizerContextCreate (&desc, &context);
assert(error == FFX_OK );

// ...

FfxErrorCode  error = ffxBrixelizerContextDestroy (context);
assert(error == FFX_OK );

// =============================================================================
// Submit an instance to the brixelizer context
// =============================================================================

FfxBrixelizerInstanceDescription  instanceDesc = {};
FfxBrixelizerInstanceID  instanceID = FFX_BRIXELIZER_INVALID_ID;

instanceDesc.maxCascade  = ...;            // The index of the highest cascade this instance will be submitted to. This helps avoid submitting many small objects to least detailed cascades.
instanceDesc.aabb  = ...;                  // An axis-aligned bounding box in world space surrounding the instance
instanceDesc.transform  = ...;             // A 3x4 matrix in row major order representing a transform to be applied to the vertices

instanceDesc.indexFormat  = ...;           // Either FFX_INDEX_TYPE_UINT16 or FFX_INDEX_TYPE_UINT32
instanceDesc.indexBuffer  = ...;           // The index of the index buffer set in ffxBrixelizerSetBuffer
instanceDesc.indexBufferOffset  = ...;     // An offset into the index buffer.
instanceDesc.triangleCount  = ...;         // The count of triangles in the index buffer.

instanceDesc.vertexBuffer  = ...;          // The index of the vertex buffer set in ffxBrixelizerSetBuffer
instanceDesc.vertexStride  = ...;          // The stride of the vertex buffer in bytes.
instanceDesc.vertexBufferOffset  = ...;    // An offset into the vertex buffer.
instanceDesc.vertexCount  = ...;           // The count of vertices in the vertex buffer.
instanceDesc.vertexFormat  = ...;          // Either FFX_SURFACE_FORMAT_R16G16B16A16_FLOAT or FFX_SURFACE_FORMAT_R32G32B32A32_FLOAT

instanceDesc.flags  = ...;                 // A combination of one or more FfxBrixelizerInstanceFlags. Currently used to specify whether an instance is static or dynamic.
instanceDesc.outInstanceID  = &instanceID; // An optional pointer to an FfxBrixelizerInstanceID for writing the ID of the created instance. This is required for static instances and unused for dynamic instances.


// Create instances for a given context with the ffxBrixelizerCreateInstance function.
// Static instances are persistent across frames. Dynamic instances are discarded after a single frame.
FfxErrorCode  error = ffxBrixelizerCreateInstance(&context, &instanceDesc);
assert(error == FFX_OK );

// ...

// Later if the static geometry changes instances may be deleted as follows
error = ffxBrixelizerDeleteInstance(&context, instanceID);
assert(error == FFX_OK );

// =============================================================================
// Brixelizer buffer registration
// =============================================================================

// Register vertex/index buffers to Brixelizer.
FfxBrixelizerBufferDescription  *bufferDescs = (FfxBrixelizerBufferDescription *)malloc(numVertexAndIndexBuffers * sizeof(*bufferDescs));
uint32_t *bufferIndices = (uint32_t*)malloc(numVertexAndIndexBuffers * sizeof(*bufferIndices));

for (uint32_t i = 0; i < numVertexAndIndexBuffers; ++i) {
    bufferDescs[i].buffer  = ffxGetResource (...);
    bufferDescs[i].outIndex  = &bufferIndices[i];
}
FfxErrorCode  error = ffxBrixelizerRegisterBuffers (&context, bufferDescs, numVertexAndIndexBuffers);
assert(error == FFX_OK );

free(bufferDescs);

// ...

// Unregister buffers from Brixelizer.
error = ffxBrixelizerUnregisterBuffers (&context, bufferIndices, numVertexAndIndexBuffers);
assert(error == FFX_OK );

free(bufferIndices);

// =============================================================================
// Brixelizer frame update
// =============================================================================

FfxBrixelizerStats  stats = {};
size_t scratchSize = 0;

FfxBrixelizerUpdateDescription  desc = {};
desc.frameIndex  = ...;              // The index of the current frame.
desc.sdfCenter [3] = ...;            // The center of the cascades.
desc.populateDebugAABBsFlags  = ...; // Flags determining which AABBs to draw in a debug visualization. See FfxBrixelizerPopulateDebugAABBsFlag.
desc.debugVisualizationDesc  = ...;  // An optional debug visualization description. If this parameter is set to NULL no debug visualization is drawn.
desc.maxReferences  = ...;           // The maximum number of triangle voxel references to be stored in the update.
desc.triangleSwapSize  = ...;        // The size of the swap space available to be used for storing triangles in the update.
desc.maxBricksPerBake  = ...;        // The maximum number of bricks to be updated.

desc.resources .sdfAtlas     = ffxGetResource (...);        // A resource for storing the SDF atlas.
desc.resources .brickAABBs   = ffxGetResource (...);        // A resource for storing the AABBs for the bricks.
for (uint32_t i = 0; i < numCascadeResources; ++i) {
    desc.resources .cascadeResources [i].aabbTree  = ffxGetResource (...);        // A resource for storing the AABB tree for the cascade.
    desc.resources .cascadeResources [i].brickMap  = ffxGetResource (...);        // A resource for storing the brick map for the cascade.
}

desc.outScratchBufferSize  = &scratchSize; // An optional pointer to a size_t to receive the amount of GPU scratch space required for the update.
desc.outStats  = &stats;                   // An optional pointer to an FfxBrixelizerStats struct receiving stats from the pass.

FfxBrixelizerBakedUpdateDescription  bakedUpdateDesc = {};
FfxErrorCode  error = ffxBrixelizerBakeUpdate (&context, &desc, &bakedUpdateDesc);
assert(error == FFX_OK );

// Create a GPU buffer with at least as much storage as scratchSize for use as scratch space
FfxResource  scratchBuffer = ffxGetResource (...);

// call frame update
FfxErrorCode  error = ffxBrixelizerUpdate (&context, &bakedUpdateDesc, scratchBuffer, commandList);
assert(error == FFX_OK );

// =============================================================================
// Using Brixelizer in a shader
// =============================================================================

FfxBrixelizerContextInfo  contextInfo = {};
FfxErrorCode  error = ffxBrixelizerGetContextInfo (&context, &contextInfo);
assert(error == FFX_OK );

// copy the contents of contextInfo to a constant buffer for use by the shader
// and bind the resources passed in to context creation for the:
//   * SDF atlas
//   * Brick AABB map
//   * Cascade brick map (for each cascade)
//   * Cascade AABB tree (for each cascade)
// to the shader.

// =============================================================================
// Create/destroy a Brixelizer context
// =============================================================================

FfxBrixelizerRawContextDescription  desc = {};
desc.maxDebugAABBs     = ...;                  // Maximum number of debug AABBs to be stored for use in debug visualization
desc.flags             = ...;                  // Flags for context creation. See <c><i>FfxBrixelizerContextFlags</i></c>.
desc.backendInterface  = ...;                  // FFX backend interface

FfxBrixelizerContext  context = {};
FfxErrorCode  error = ffxBrixelizerRawContextCreate (&context, &desc);
assert(error == FFX_OK );

// ...

error = ffxBrixelizerRawContextDestroy (&context);
assert(error == FFX_OK );

// =============================================================================
// Create/destroy a cascade
// =============================================================================

uint32_t cascadeIndex = ...; // Index of the cascade to create, between 0 and FFX_BRIXELIZER_MAX_CASCADES - 1

FfxBrixelizerRawCascadeDescription  cascadeDesc = {};
cascadeDesc.brickSize      = ...;                  // Edge length in world space units of a single brick
cascadeDesc.cascadeMin [3] = ...;                  // Corner in world space of the first brick
cascadeDesc.index          = cascadeIndex;         // Cascade index

error = ffxBrixelizerRawContextCreateCascade (&context, &cascadeDesc);
assert(error == FFX_OK );

// ...

// Destroy the cascade. Unregisters the cascade resources from the Brixelizer context.
error = ffxBrixelizerRawContextDestroyCascade (&context, cascadeIndex);
assert(error == FFX_OK );

// =============================================================================
// Create/destroy instances
// =============================================================================

FfxBrixelizerRawInstanceDescription  *instanceDescs = (FfxBrixelizerRawInstanceDescription *)malloc(numInstances * sizeof(*instanceDescs));
FfxBrixelizerInstanceID  *instanceIDs = (FfxBrixelizerInstanceID *)malloc(numInstances * sizeof(*instanceIDs));

for (uint32_t i = 0; i < numInstances; ++i) {
    FfxBrixelizerRawInstanceDescription  *instanceDesc = &instanceDescs[i];

    instanceDesc->aabbMin             = ...;             // The minimum coordinates of an AABB surrounding the instance.
    instanceDesc->aabbMax             = ...;             // The maximum coordinates of an AABB surrounding the instance.
    instanceDesc->transform           = ...;             // A tranform of the instance into world space. The transform is in row major order.

    instanceDesc->indexFormat         = ...;             // The format of the index buffer. Accepted formats are FFX_INDEX_UINT16 or FFX_INDEX_UINT32.
    instanceDesc->indexBuffer         = ...;             // The index of the index buffer set with ffxBrixelizerContextSetBuffer.
    instanceDesc->indexBufferOffset   = ...;             // An offset into the index buffer.
    instanceDesc->triangleCount       = ...;             // The count of triangles in the index buffer.

    instanceDesc->vertexBuffer        = ...;             // The index of the vertex buffer set with ffxBrixelizerContextSetBuffer.
    instanceDesc->vertexStride        = ...;             // The stride of the vertex buffer in bytes.
    instanceDesc->vertexBufferOffset  = ...;             // An offset into the vertex buffer.
    instanceDesc->vertexCount         = ...;             // The count of vertices in the vertex buffer.
    instanceDesc->vertexFormat        = ...;             // The format of vertices in the vertex buffer. Accepted values are FFX_SURFACE_FORMAT_R16G16B16A16_FLOAT and FFX_SURFACE_FORMAT_R32G32B32A32_FLOAT.

    instanceDesc->flags               = ...;             // Flags for the instance. See FfxBrixelizerInstanceFlags.
    instanceDesc->outInstanceID       = &instanceIDs[i]; // Pointer to an FfxBrixelizerInstanceID to receive the ID of the created instance.
}

FfxBrixelizerInstanceID  instanceID = FFX_BRIXELIZER_INVALID_ID;
error = ffxBrixelizerContextCreateInstances(&context, instanceDescs, numInstances);
assert(error == FFX_OK );

free(instanceDescs)

// ...

error = ffxBrixelizerContextDestroyInstances(&context, instanceIDs, numInstances);
assert(error == FFX_OK );

free(instanceIDs);

// =============================================================================
// Register/unregister vertex and index buffers
// =============================================================================

// Register vertex/index buffers to Brixelizer.
FfxBrixelizerBufferDescription  *bufferDescs = (FfxBrixelizerBufferDescription *)malloc(numVertexAndIndexBuffers * sizeof(*bufferDescs));
uint32_t *bufferIndices = (uint32_t*)malloc(numVertexAndIndexBuffers * sizeof(*bufferIndices));

for (uint32_t i = 0; i < numVertexAndIndexBuffers; ++i) {
    bufferDescs[i].buffer  = ffxGetResource (...);
    bufferDescs[i].outIndex  = &bufferIndices[i];
}
FfxErrorCode  error = ffxBrixelizerRawContextRegisterBuffers (&context, bufferDescs, numVertexAndIndexBuffers);
assert(error == FFX_OK );

free(bufferDescs);

// ...

// Unregister buffers from Brixelizer.
error = ffxBrixelizerRawContextUnregisterBuffers (&context, bufferIndices, numVertexAndIndexBuffers);
assert(error == FFX_OK );

free(bufferIndices);

// =============================================================================
// Calculate a frame of brixelizer
// =============================================================================

FfxCommandList  commandList = ffxGetCommandList (...);
error = ffxBrixelizerRawContextFlushInstances (&context, commandList);
assert(error == FFX_OK );

FfxBrixelizerResources  resources = {};
resources.sdfAtlas          = ffxGetResource (...);  // SDF atlas resource
resources.brickAABBs        = ffxGetResource (...);  // Brick AABBs resource
for (uint32_t i = 0; i < numCascadeResources; ++i) {
    resources.cascadeResources [i].aabbTree  = ffxGetResource (...);        // A resource for storing the AABB tree for the cascade.
    resources.cascadeResources [i].brickMap  = ffxGetResource (...);        // A resource for storing the brick map for the cascade.
}

error = ffxBrixelizerRawContextBegin (&context, &resources);
assert(error == FFX_OK );

// Reset/clear a cascade. Frees all bricks from the cascade allowing geometry to be built to the cascade from scratch.

error = ffxBrixelizerRawContextResetCascade (&context, cascadeIndex);
assert(error == FFX_OK );


// Create jobs

FfxBrixelizerRawJobDescription  jobs[NUM_JOBS] = {};

for (uint32_t i = 0; i < NUM_JOBS; ++i) {
    FfxBrixelizerRawJobDescription  *job = &jobs[i];
    job->aabbMin      = ...;   // The mimimum corner of the AABB of the job.
    job->aabbMax      = ...;   // The maximum corner of the AABB of the job.
    job->flags        = ...;   // Flags for the job (to be set from FfxBrixelizerJobFlags).
    job->instanceIdx  = ...;   // The ID for an instance for the job.
}

// Update cascades

FfxBrixelizerRawCascadeUpdateDescription  updateDescs[NUM_CASCADES_TO_UPDATE] = {};
size_t scratchSpaceSize = 0;

for (uint32_t i = 0; i < NUM_CASCADES_TO_UPDATE; ++i) {
    FfxBrixelizerRawCascadeUpdateDescription  *desc = &updateDescs[i];
    desc->maxReferences     = ...;          // Storage for triangle->voxel references
    desc->triangleSwapSize  = ...;          // Scratch storage for triangles
    desc->maxBricksPerBake  = ...;          // Max SDF brick baked per update
    desc->cascadeIndex      = ...;          // Target Cascade
    desc->jobs              = jobs;         // A pointer to an array of jobs.
    desc->numJobs           = NUM_JOBS;     // The number of jobs in the array pointed to by jobs.
    desc->cascadeMin        = ...;          // Lower corner of the first brick in world space.
    desc->clipmapOffset     = ...;          // Changing that invalidates portion of the cascade. it's an offset in the voxel->brick table.
    desc->flags             = ...;          // See FfxBrixelizerCascadeUpdateFlags.

    size_t thisScratchSpaceSize = 0;
    error = ffxBrixelizerRawContextGetScratchMemorySize (&context, desc, &thisScratchSpaceSize);
    assert(error == FFX_OK );
    scratchSpaceSize = max(scratchSpaceSize, thisScratchSpaceSize);
}

FfxResource  scratchBuffer = ffxGetResource (...); // A resource of size at least scratchSpaceSize to be used as the scratch space for brixelizer

for (uint32_t i = 0; i < NUM_CASCADES_TO_UPDATE; ++i) {
    FfxBrixelizerCascadeUpdateDescription *desc = &updateDescs[i];
    error = ffxBrixelizerRawContextUpdateCascade (&context, desc, scratchBuffer);
    assert(error == FFX_OK );
}

// Merge cascades

for (uint32_t i = 0; i < NUM_CASCADES_TO_MERGE; ++i) {
    uint32_t sourceCascadeIndex1 = ...; // index of first source cascade
    uint32_t sourceCascadeIndex2 = ...; // index of second source cascade
    uint32_t destCascadeIndex    = ...; // index of destination cascade
    error = ffxBrixelizerRawContextMergeCascades (&context, sourceCascadeIndex1, sourceCascadeIndex2, destCascadeIndex);
    assert(error == FFX_OK );
}

// Build cascade AABB trees

for (uint32_t i = 0; i < NUM_AABB_TREES_TO_BUILD; ++i) {
    uint32_t cascadeIndex = ...; // index of cascade to build an AABB tree for
    ffxBrixelizerRawContextBuildAABBTree (&context, cascadeIndex);
    assert(error == FFX_OK );
}

// Optionally do debug visualization

if (doDebugVisualization) {
    FfxBrixelizerDebugVisualizationDescription  desc = {};
    desc.inverseViewMatrix        = ...;           // Inverse view matrix for the scene in row major order.
    desc.inverseProjectionMatrix  = ...;           // Inverse projection matrix for the scene in row major order.
    desc.debugState               = ...;           // An FfxBrixelizerTraceDebugModes determining what kind of debug output to draw.
    desc.startCascadeIndex        = ...;           // The index of the most detailed cascade in the cascade chain.
    desc.endCascadeIndex          = ...;           // The index of the least detailed cascade in the cascade chain.
    desc.sdfSolveEps              = ...;           // The epsilon value used in SDF ray marching.
    desc.tMin                     = ...;           // The tMin value for minimum ray intersection.
    desc.tMax                     = ...;           // The tMax value for maximum ray intersection.
    desc.renderWidth              = ...;           // The width of the output resource.
    desc.renderHeight             = ...;           // The height of the output resource.
    desc.output                   = ...;           // An FfxResource to draw the debug visualization to.

    desc.commandList              = ...;           // An FfxCommandList to write the draw commands to.
    desc.numDebugAABBInstanceIDs  = ...;           // The number of FfxBrixelizerInstanceIDs in the debugAABBInstanceIDs array.
    desc.debugAABBInstanceIDs     = ...;           // An array of FfxBrixelizerInstanceIDs for instances to draw the bounding boxes of.

    for (uint32_t i = 0; i < numCascades; ++i) {
        desc.cascadeDebugAABB [i] = ...;       // An array of flags showing what AABB debug output to draw for each cascade.
    }

    error = ffxBrixelizerRawContextDebugVisualization (&context, &desc);
    assert(error == FFX_OK );
}

error = ffxBrixelizerRawContextEnd (&context);
assert(error == FFX_OK );

error = ffxBrixelizerRawContextSubmit (&context, commandList);
assert(error == FFX_OK );

// =============================================================================
// Using Brixelizer in a shader
// =============================================================================

FfxBrixelizerContextInfo  contextInfo = {};
FfxErrorCode  error = ffxBrixelizerRawContextGetInfo (&context, &contextInfo);
assert(error == FFX_OK );

// copy the contents of contextInfo to a constant buffer for use by the shader
// and bind the resources passed in to context creation for the:
//   * SDF atlas
//   * Brick AABB map
//   * Cascade brick map (for each cascade)
//   * Cascade AABB tree (for each cascade)
// to the shader.

// =============================================================================
// Misc
// =============================================================================

// Read back counters from brixelizer for understanding performance

FfxBrixelizerDebugCounters  debugCounters = {};
error = ffxBrixelizerRawContextGetDebugCounters (&context, &debugCounters);
assert(error == FFX_OK );

FfxBrixelizerScratchCounters  scratchCounters = {};
uint32_t cascadeIndex = ...; // Index of cascade to query
error = ffxBrixelizerRawContextGetCascadeCounters (&context, cascadeIndex, &scratchCounters);
assert(error == FFX_OK );