FidelityFX Breadcrumbs

FidelityFX Breadcrumbs runtime library.

Enumerations

Name

Description

FfxBreadcrumbsInitializationFlagBits

An enumeration of bit flags used when creating a “FfxBreadcrumbsContext“. See “FfxBreadcrumbsContextDescription“.
FFX_BREADCRUMBS_PRINT_FINISHED_LISTS = (1<<0) – A bit indicating that fully finished command lists will be expanded during status printing (otherwise their entries will be collapsed).
FFX_BREADCRUMBS_PRINT_NOT_STARTED_LISTS = (1<<1) – A bit indicating that command lists that haven’t started execution on GPU yet will be expanded during status printing (otherwise their entries will be collapsed).
FFX_BREADCRUMBS_PRINT_FINISHED_NODES = (1<<3) – A bit indicating that nested markers which already have finished execution will be expanded during status printing (otherwise they will merged into top level marker).
FFX_BREADCRUMBS_PRINT_NOT_STARTED_NODES = (1<<4) – A bit indicating that nested markers which haven’t started execution yet will be expanded during status printing (otherwise they will merged into top level marker).
FFX_BREADCRUMBS_PRINT_EXTENDED_DEVICE_INFO = (1<<5) – A bit indicating that additional info about active GPU will be printed into output status.
FFX_BREADCRUMBS_PRINT_SKIP_DEVICE_INFO = (1<<6) – A bit indicating that no info about active GPU will be printed into outpus status.
FFX_BREADCRUMBS_PRINT_SKIP_PIPELINE_INFO = (1<<7) – A bit indicating no info about pipelines used for commands recorded between markers will be printed into output status.
FFX_BREADCRUMBS_ENABLE_THREAD_SYNCHRONIZATION = (1<<8) – A bit indicating if internal synchronization should be applied (when using Breadcrumbs concurrently from multiple threads).

FfxBreadcrumbsMarkerType

Type of currently recorded marker, purely informational.
FFX_BREADCRUMBS_MARKER_PASS – Marker for grouping sets of commands. It is required to supply custom name for this type.
FFX_BREADCRUMBS_MARKER_BEGIN_EVENT
FFX_BREADCRUMBS_MARKER_BEGIN_QUERY
FFX_BREADCRUMBS_MARKER_CLEAR_DEPTH_STENCIL
FFX_BREADCRUMBS_MARKER_CLEAR_RENDER_TARGET
FFX_BREADCRUMBS_MARKER_CLEAR_STATE
FFX_BREADCRUMBS_MARKER_CLEAR_UNORDERED_ACCESS_FLOAT
FFX_BREADCRUMBS_MARKER_CLEAR_UNORDERED_ACCESS_UINT
FFX_BREADCRUMBS_MARKER_CLOSE
FFX_BREADCRUMBS_MARKER_COPY_BUFFER_REGION
FFX_BREADCRUMBS_MARKER_COPY_RESOURCE
FFX_BREADCRUMBS_MARKER_COPY_TEXTURE_REGION
FFX_BREADCRUMBS_MARKER_COPY_TILES
FFX_BREADCRUMBS_MARKER_DISCARD_RESOURCE
FFX_BREADCRUMBS_MARKER_DISPATCH
FFX_BREADCRUMBS_MARKER_DRAW_INDEXED_INSTANCED
FFX_BREADCRUMBS_MARKER_DRAW_INSTANCED
FFX_BREADCRUMBS_MARKER_END_EVENT
FFX_BREADCRUMBS_MARKER_END_QUERY
FFX_BREADCRUMBS_MARKER_EXECUTE_BUNDLE
FFX_BREADCRUMBS_MARKER_EXECUTE_INDIRECT
FFX_BREADCRUMBS_MARKER_RESET
FFX_BREADCRUMBS_MARKER_RESOLVE_QUERY_DATA
FFX_BREADCRUMBS_MARKER_RESOLVE_SUBRESOURCE
FFX_BREADCRUMBS_MARKER_RESOURCE_BARRIER
FFX_BREADCRUMBS_MARKER_SET_COMPUTE_ROOT_SIGNATURE
FFX_BREADCRUMBS_MARKER_SET_DESCRIPTORS_HEAP
FFX_BREADCRUMBS_MARKER_SET_GRAPHICS_ROOT_SIGNATURE
FFX_BREADCRUMBS_MARKER_SET_PIPELINE_STATE
FFX_BREADCRUMBS_MARKER_SET_PREDICATION
FFX_BREADCRUMBS_MARKER_ATOMIC_COPY_BUFFER_UINT
FFX_BREADCRUMBS_MARKER_ATOMIC_COPY_BUFFER_UINT64
FFX_BREADCRUMBS_MARKER_RESOLVE_SUBRESOURCE_REGION
FFX_BREADCRUMBS_MARKER_SET_SAMPLE_POSITION
FFX_BREADCRUMBS_MARKER_SET_VIEW_INSTANCE_MASK
FFX_BREADCRUMBS_MARKER_WRITE_BUFFER_IMMEDIATE
FFX_BREADCRUMBS_MARKER_SET_PROTECTED_RESOURCE_SESSION
FFX_BREADCRUMBS_MARKER_BEGIN_RENDER_PASS
FFX_BREADCRUMBS_MARKER_BUILD_RAY_TRACING_ACCELERATION_STRUCTURE
FFX_BREADCRUMBS_MARKER_COPY_RAY_TRACING_ACCELERATION_STRUCTURE
FFX_BREADCRUMBS_MARKER_DISPATCH_RAYS
FFX_BREADCRUMBS_MARKER_EMIT_RAY_TRACING_ACCELERATION_STRUCTURE_POSTBUILD_INFO
FFX_BREADCRUMBS_MARKER_END_RENDER_PASS
FFX_BREADCRUMBS_MARKER_EXECUTE_META_COMMANDS
FFX_BREADCRUMBS_MARKER_INITIALIZE_META_COMMANDS
FFX_BREADCRUMBS_MARKER_SET_RAY_TRACING_STATE
FFX_BREADCRUMBS_MARKER_SET_SHADING_RATE
FFX_BREADCRUMBS_MARKER_SET_SHADING_RATE_IMAGE
FFX_BREADCRUMBS_MARKER_BEGIN_CONDITIONAL_RENDERING_EXT
FFX_BREADCRUMBS_MARKER_BEGIN_DEBUG_UTILS_LABEL_EXT
FFX_BREADCRUMBS_MARKER_BEGIN_QUERY_INDEXED_EXT
FFX_BREADCRUMBS_MARKER_BEGIN_RENDER_PASS_2
FFX_BREADCRUMBS_MARKER_BEGIN_TRANSFORM_FEEDBACK_EXT
FFX_BREADCRUMBS_MARKER_BIND_DESCRIPTOR_SETS
FFX_BREADCRUMBS_MARKER_BIND_PIPELINES
FFX_BREADCRUMBS_MARKER_BIND_SHADING_RATE_IMAGE_NV
FFX_BREADCRUMBS_MARKER_BLIT_IMAGE
FFX_BREADCRUMBS_MARKER_BUILD_ACCELERATION_STRUCTURE_NV
FFX_BREADCRUMBS_MARKER_CLEAR_ATTACHMENTS
FFX_BREADCRUMBS_MARKER_CLEAR_COLOR_IMAGE
FFX_BREADCRUMBS_MARKER_CLEAR_DEPTH_STENCIL_IMAGE
FFX_BREADCRUMBS_MARKER_COPY_ACCELERATION_STRUCTURE_NV
FFX_BREADCRUMBS_MARKER_COPY_BUFFER
FFX_BREADCRUMBS_MARKER_COPY_BUFFER_TO_IMAGE
FFX_BREADCRUMBS_MARKER_COPY_IMAGE
FFX_BREADCRUMBS_MARKER_COPY_IMAGE_TO_BUFFER
FFX_BREADCRUMBS_MARKER_DEBUG_MARKER_BEGIN_EXT
FFX_BREADCRUMBS_MARKER_DEBUG_MARKER_END_EXT
FFX_BREADCRUMBS_MARKER_DEBUG_MARKER_INSERT_EXT
FFX_BREADCRUMBS_MARKER_DISPATCH_BASE
FFX_BREADCRUMBS_MARKER_DISPATCH_INDIRECT
FFX_BREADCRUMBS_MARKER_DRAW
FFX_BREADCRUMBS_MARKER_DRAW_INDEXED
FFX_BREADCRUMBS_MARKER_DRAW_INDEXED_INDIRECT
FFX_BREADCRUMBS_MARKER_DRAW_INDEXED_INDIRECT_COUNT
FFX_BREADCRUMBS_MARKER_DRAW_INDIRECT
FFX_BREADCRUMBS_MARKER_DRAW_INDIRECT_BYTE_COUNT_EXT
FFX_BREADCRUMBS_MARKER_DRAW_INDIRECT_COUNT
FFX_BREADCRUMBS_MARKER_DRAW_MESH_TASKS_INDIRECT_COUNT_NV
FFX_BREADCRUMBS_MARKER_DRAW_MESH_TASKS_INDIRECT_NV
FFX_BREADCRUMBS_MARKER_DRAW_MESH_TASKS_NV
FFX_BREADCRUMBS_MARKER_END_CONDITIONAL_RENDERING_EXT
FFX_BREADCRUMBS_MARKER_END_DEBUG_UTILS_LABEL_EXT
FFX_BREADCRUMBS_MARKER_END_QUERY_INDEXED_EXT
FFX_BREADCRUMBS_MARKER_END_RENDER_PASS_2
FFX_BREADCRUMBS_MARKER_END_TRANSFORM_FEEDBACK_EXT
FFX_BREADCRUMBS_MARKER_EXECUTE_COMMANDS
FFX_BREADCRUMBS_MARKER_FILL_BUFFER
FFX_BREADCRUMBS_MARKER_INSERT_DEBUG_UTILS_LABEL_EXT
FFX_BREADCRUMBS_MARKER_NEXT_SUBPASS
FFX_BREADCRUMBS_MARKER_NEXT_SUBPASS_2
FFX_BREADCRUMBS_MARKER_PIPELINE_BARRIER
FFX_BREADCRUMBS_MARKER_PROCESS_COMMANDS_NVX
FFX_BREADCRUMBS_MARKER_RESERVE_SPACE_FOR_COMMANDS_NVX
FFX_BREADCRUMBS_MARKER_RESET_EVENT
FFX_BREADCRUMBS_MARKER_RESET_QUERY_POOL
FFX_BREADCRUMBS_MARKER_RESOLVE_IMAGE
FFX_BREADCRUMBS_MARKER_SET_CHECKPOINT_NV
FFX_BREADCRUMBS_MARKER_SET_EVENT
FFX_BREADCRUMBS_MARKER_SET_PERFORMANCE_MARKER_INTEL
FFX_BREADCRUMBS_MARKER_SET_PERFORMANCE_OVERRIDE_INTEL
FFX_BREADCRUMBS_MARKER_SET_PERFORMANCE_STREAM_MARKER_INTEL
FFX_BREADCRUMBS_MARKER_SET_SAMPLE_LOCATIONS_EXT
FFX_BREADCRUMBS_MARKER_SET_VIEWPORT_SHADING_RATE_PALETTE_NV
FFX_BREADCRUMBS_MARKER_TRACE_RAYS_NV
FFX_BREADCRUMBS_MARKER_UPDATE_BUFFER
FFX_BREADCRUMBS_MARKER_WAIT_EVENTS
FFX_BREADCRUMBS_MARKER_WRITE_ACCELERATION_STRUCTURES_PROPERTIES_NV
FFX_BREADCRUMBS_MARKER_WRITE_BUFFER_MARKER_AMD
FFX_BREADCRUMBS_MARKER_WRITE_BUFFER_MARKER_2_AMD
FFX_BREADCRUMBS_MARKER_WRITE_TIMESTAMP

Structs

Name

Description

FfxBreadcrumbsCommandListDescription

Description for new command list to be enabled for writing AMD FidelityFX Breadcrumbs Library markers.

FfxBreadcrumbsContext

A structure encapsulating the FidelityFX Breadcrumbs context.

FfxBreadcrumbsContextDescription

A structure encapsulating the parameters required to initialize FidelityFX Breadcrumbs.

FfxBreadcrumbsMarkersStatus

Output with current AMD FidelityFX Breadcrumbs Library markers log for post-mortem analysis.

FfxBreadcrumbsNameTag

Wrapper for custom Breadcrumbs name tags with indicator whether to perform copy on them.

FfxBreadcrumbsPipelineStateDescription

Description for pipeline state that will be used to tag breadcrumbs markers.

Functions

Return type

Description

FFX_API FfxErrorCode

Create a FidelityFX Breadcrumbs context from the parameters programmed to the “FfxBreadcrumbsContextDescription“ structure.

FFX_API FfxErrorCode

Destroy the FidelityFX Breadcrumbs context.

FFX_API FfxErrorCode

Begins new frame of execution for FidelityFX Breadcrumbs.

FFX_API FfxErrorCode

Register new command list for current frame FidelityFX Breadcrumbs operations.

FFX_API FfxErrorCode

Register new pipeline state to associate later with FidelityFX Breadcrumbs operations.

FFX_API FfxErrorCode

Associate specific pipeline state with following FidelityFX Breadcrumbs markers.

FFX_API FfxErrorCode

ffxBreadcrumbsBeginMarker ( FfxBreadcrumbsContext * pContext, FfxCommandList commandList, FfxBreadcrumbsMarkerType type, const FfxBreadcrumbsNameTag * pName )
Begin new FidelityFX Breadcrumbs marker section.

FFX_API FfxErrorCode

End FidelityFX Breadcrumbs marker section.

FFX_API FfxErrorCode

Gather information about current FidelityFX Breadcrumbs markers status.

FFX_API FfxVersionNumber

Queries the effect version number.

Macros

Name

Description

FFX_BREADCRUMBS_CONTEXT_COUNT 1

FidelityFX Breadcrumbs context count.

FFX_BREADCRUMBS_CONTEXT_SIZE (128)

The size of the context specified in 32bit values.

FFX_BREADCRUMBS_MARKER_LIST

List of marker types to be used in X() macro.

FFX_BREADCRUMBS_MAX_MARKERS_PER_BLOCK ((1U << 31) – 1U)

Maximal number of markers that can be written into single memory block.

FFX_BREADCRUMBS_VERSION_MAJOR (1)

FidelityFX Breadcrumbs major version.

FFX_BREADCRUMBS_VERSION_MINOR (0)

FidelityFX Breadcrumbs minor version.

FFX_BREADCRUMBS_VERSION_PATCH (0)

FidelityFX Breadcrumbs patch version.

Detailed description

FidelityFX Breadcrumbs runtime library.

Global functions

ffxBreadcrumbsContextCreate

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsContextCreate (
    FfxBreadcrumbsContext * pContext,
    const FfxBreadcrumbsContextDescription * pContextDescription
)

Create a FidelityFX Breadcrumbs context from the parameters programmed to the FfxBreadcrumbsContextDescription structure.

The context structure is the main object used to interact with the Breadcrumbs API, and is responsible for the management of the internal buffers used by the Breadcrumbs algorithm. For each provided queue there will be created a buffer that will hold contents of the saved markers, awaiting for retrieval per call to ffxBreadcrumbsPrintStatus()

When choosing the number of frames to save markers for, specified in the frameHistoryLength field of FfxBreadcrumbsContextDescription, typically can be set to the number of frames in flight in the application, but for longer history it can be increased.

Buffers for markers are allocated at fixed size, allowing for certain number of markers to be saved in them. The size of this buffers are determined by maxMarkersPerMemoryBlock field of FfxBreadcrumbsContextDescription. When needed new ones are created but to avoid multiple allocations you can estimate how many markers will be used in single frame.

The FfxBreadcrumbsContext should be destroyed when use of it is completed, typically when an application is unloaded. To destroy the Breadcrumbs context you should call ffxBreadcrumbsContextDestroy.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure to populate.

pContextDescription

A pointer to a FfxBreadcrumbsContextDescription structure.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either pContext or contextDescription was NULL.

FFX_ERROR_INCOMPLETE_INTERFACE

The operation failed because the FfxBreadcrumbsContextDescription.backendInterface was not fully specified.

FFX_ERROR_BACKEND_API_ERROR

The operation failed because of an error returned from the backend.


ffxBreadcrumbsContextDestroy

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsContextDestroy (FfxBreadcrumbsContext * pContext)

Destroy the FidelityFX Breadcrumbs context.

Should always be called from a single thread for same context.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure to destroy.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either pContext was NULL.


ffxBreadcrumbsStartFrame

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsStartFrame (FfxBreadcrumbsContext * pContext)

Begins new frame of execution for FidelityFX Breadcrumbs.

Should always be called from a single thread for same context.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either pContext was NULL.


ffxBreadcrumbsRegisterCommandList

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsRegisterCommandList (
    FfxBreadcrumbsContext * pContext,
    const FfxBreadcrumbsCommandListDescription * pCommandListDescription
)

Register new command list for current frame FidelityFX Breadcrumbs operations.

After call to ffxBreadcrumbsStartFrame() every previously used list has to be registered again.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure.

pCommandListDescription

A pointer to a FfxBreadcrumbsCommandListDescription structure.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either pContext or pCommandListDescription was NULL.

FFX_ERROR_INVALID_ARGUMENT

The operation failed because given command list has been already registered.


ffxBreadcrumbsRegisterPipeline

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsRegisterPipeline (
    FfxBreadcrumbsContext * pContext,
    const FfxBreadcrumbsPipelineStateDescription * pPipelineDescription
)

Register new pipeline state to associate later with FidelityFX Breadcrumbs operations.

Information about pipeline is preserved across frames so only single call after creation of pipeline is needed.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure.

pPipelineDescription

A pointer to a FfxBreadcrumbsPipelineStateDescription structure.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either pContext or pPipelineDescription was NULL.

FFX_ERROR_INVALID_ARGUMENT

The operation failed because given pipeline has been already registered or pPipelineDescription contains incorrect data.


ffxBreadcrumbsSetPipeline

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsSetPipeline (
    FfxBreadcrumbsContext * pContext,
    FfxCommandList  commandList,
    FfxPipeline  pipeline
)

Associate specific pipeline state with following FidelityFX Breadcrumbs markers.

When recorded commands use specific pipelines you can save this information, associating said pipelines with recorded markers, so later on additional information can be displayed when using ffxBreadcrumbsPrintStatus(). To reset currently used pipeline just pass NULL as pipeline param.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure.

commandList

Previously registered command list.

pipeline

Previously registered pipeline.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either context or commandList was NULL.

FFX_ERROR_INVALID_ARGUMENT

The operation failed because given pipeline or command list has not been registered yet.


ffxBreadcrumbsBeginMarker

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsBeginMarker (
    FfxBreadcrumbsContext * pContext,
    FfxCommandList  commandList,
    FfxBreadcrumbsMarkerType  type,
    const FfxBreadcrumbsNameTag * pName
)

Begin new FidelityFX Breadcrumbs marker section.

New section has to be ended with ffxBreadcrumbsEndMarker() but multiple ffxBreadcrumbsBeginMarker() nesting calls are possible.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure.

commandList

Previously registered command list.

type

Type of the marker section.

pName

Custom name for the marker section. Have to contain correct string if type is FFX_BREADCRUMBS_MARKER_PASS().

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either pContext or pName was NULL.

FFX_ERROR_INVALID_ARGUMENT

The operation failed because given command list has not been registered yet or pName doesn’t contain correct string.

FFX_ERROR_BACKEND_API_ERROR

The operation failed because of an error returned from the backend.


ffxBreadcrumbsEndMarker

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsEndMarker (
    FfxBreadcrumbsContext * pContext,
    FfxCommandList  commandList
)

End FidelityFX Breadcrumbs marker section.

Has to be preceeded by ffxBreadcrumbsBeginMarker().

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure.

commandList

Previously registered command list.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because pContext was NULL.

FFX_ERROR_INVALID_ARGUMENT

The operation failed because given command list has not been registered yet.


ffxBreadcrumbsPrintStatus

Copied!

FFX_API  FfxErrorCode  ffxBreadcrumbsPrintStatus (
    FfxBreadcrumbsContext * pContext,
    FfxBreadcrumbsMarkersStatus * pMarkersStatus
)

Gather information about current FidelityFX Breadcrumbs markers status.

After receiving device lost error on GPU you can use this method to print post-mortem log of markers execution to determine which commands in which frame were in flight during the crash. Should always be called from a single thread.

Parameters:

pContext

A pointer to a FfxBreadcrumbsContext structure.

pMarkersStatus

Buffer with post-mortem log of Breadcrumbs markers.

Return values:

FFX_OK

The operation completed successfully.

FFX_ERROR_INVALID_POINTER

The operation failed because either pContext or pMarkersStatus was NULL.


ffxBreadcrumbsGetEffectVersion

Copied!

FFX_API  FfxVersionNumber  ffxBreadcrumbsGetEffectVersion ()

Queries the effect version number.

Returns:

The SDK version the effect was built with.


Macros

FFX_BREADCRUMBS_CONTEXT_COUNT

Copied!

#define FFX_BREADCRUMBS_CONTEXT_COUNT 1

FidelityFX Breadcrumbs context count.

Defines the number of internal effect contexts required by Breadcrumbs


FFX_BREADCRUMBS_CONTEXT_SIZE

Copied!

#define FFX_BREADCRUMBS_CONTEXT_SIZE (128)

The size of the context specified in 32bit values.


FFX_BREADCRUMBS_MARKER_LIST

Copied!

#define FFX_BREADCRUMBS_MARKER_LIST

List of marker types to be used in X() macro.


FFX_BREADCRUMBS_MAX_MARKERS_PER_BLOCK

Copied!

#define FFX_BREADCRUMBS_MAX_MARKERS_PER_BLOCK ((1U << 31) - 1U)

Maximal number of markers that can be written into single memory block.


FFX_BREADCRUMBS_VERSION_MAJOR

Copied!

#define FFX_BREADCRUMBS_VERSION_MAJOR (1)

FidelityFX Breadcrumbs major version.


FFX_BREADCRUMBS_VERSION_MINOR

Copied!

#define FFX_BREADCRUMBS_VERSION_MINOR (0)

FidelityFX Breadcrumbs minor version.


FFX_BREADCRUMBS_VERSION_PATCH

Copied!

#define FFX_BREADCRUMBS_VERSION_PATCH (0)

FidelityFX Breadcrumbs patch version.