FramePlan And Packet API¶

FramePlan builders, DRP2 emission helpers, and packet spans used by runtime and WASM integrations.

Status: advanced/unstable

This generated page lists exported C functions and their canonical public types classified by the v0.4 C API reference policy. Raw Python ctypes call forms are documented separately.

Use this page for advanced runtime, fixture, or WASM/WebGPU integration work. Ordinary retained scene code should use scene frame artifacts.

Common workflows:

Functions: 44 Types: 12

Symbol Groups¶

Group	Functions	Types	Headers
Capability	2	1	`include/datoviz/scene/frame_plan.h`, `include/datoviz/scene/types.h`
Diagnostic	7	1	`include/datoviz/scene/frame_plan.h`, `include/datoviz/scene/types.h`
Emission	7	2	3 headers
Frame Planning	23	6	3 headers
Packet Results	5	2	`include/datoviz/scene/frame_packets.h`

Grouped function index

Capability

Function	Header
`dvz_capability_snapshot()`	`include/datoviz/scene/frame_plan.h`
`dvz_capability_snapshot_copy()`	`include/datoviz/scene/frame_plan.h`

Diagnostic

Function	Header
`dvz_diagnostic_report_add()`	`include/datoviz/scene/frame_plan.h`
`dvz_diagnostic_report_add_with_severity()`	`include/datoviz/scene/frame_plan.h`
`dvz_diagnostic_report_count()`	`include/datoviz/scene/frame_plan.h`
`dvz_diagnostic_report_error_count()`	`include/datoviz/scene/frame_plan.h`
`dvz_diagnostic_report_get()`	`include/datoviz/scene/frame_plan.h`
`dvz_diagnostic_report_get_severity()`	`include/datoviz/scene/frame_plan.h`
`dvz_diagnostic_report_init()`	`include/datoviz/scene/frame_plan.h`

Emission

Function	Header
`dvz_frame_plan_emit_config()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_emit_drp2()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_emit_drp2_ex()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_emitter_destroy()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_emitter_emit_drp2()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_emitter_emit_drp2_packets()`	`include/datoviz/scene/frame_packets.h`
`dvz_frame_plan_emitter_object_id()`	`include/datoviz/scene/frame_plan.h`

Frame Planning

Function	Header
`dvz_frame_plan()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_clear()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_compute()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_compute_read()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_compute_write()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_copy()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_copy_desc()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_copy_ex()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_destroy()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_emitter()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_json()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_json_destroy()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_node_count()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_node_get()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_node_type()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_readback()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_render()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_render_pass_role()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_render_visual()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_upload()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_upload_bytes()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_upload_desc()`	`include/datoviz/scene/frame_plan.h`
`dvz_frame_plan_upload_ex()`	`include/datoviz/scene/frame_plan.h`

Packet Results

Function	Header
`dvz_frame_plan_packet_result_destroy()`	`include/datoviz/scene/frame_packets.h`
`dvz_frame_plan_packet_result_frame_index()`	`include/datoviz/scene/frame_packets.h`
`dvz_frame_plan_packet_result_get()`	`include/datoviz/scene/frame_packets.h`
`dvz_frame_plan_packet_result_resource_version()`	`include/datoviz/scene/frame_packets.h`
`dvz_frame_plan_packet_result_status()`	`include/datoviz/scene/frame_packets.h`

Capability¶

Functions

`dvz_capability_snapshot()`¶

Return the default capability snapshot.

DvzCapabilitySnapshot dvz_capability_snapshot(void);

Field	Type	Description
return	`DvzCapabilitySnapshot`	default capability snapshot

Declared in include/datoviz/scene/frame_plan.h:104.

`dvz_capability_snapshot_copy()`¶

Copy a capability snapshot.

void dvz_capability_snapshot_copy(
    DvzCapabilitySnapshot * dst,
    const DvzCapabilitySnapshot * src
);

Field	Type	Description
`dst`	`DvzCapabilitySnapshot` *	the destination snapshot
`src`	`const` `DvzCapabilitySnapshot` *	the source snapshot

Declared in include/datoviz/scene/frame_plan.h:115.

Types

DvzCapabilitySnapshot · record

struct DvzCapabilitySnapshot {
    uint32_t struct_size;
    uint32_t flags;
    uint64_t max_buffer_size;
    uint32_t max_texture_dimension_2d;
    uint32_t max_bind_groups;
    uint32_t max_vertex_buffers;
    uint32_t max_color_attachments;
    uint32_t max_color_sample_count;
    uint32_t max_depth_sample_count;
    _Bool shader_format_wgsl;
    _Bool shader_format_glsl;
    _Bool render_target_format_rgba16float;
    _Bool render_target_format_r16float;
    _Bool supports_render_target_sampling;
    _Bool supports_color_blending;
    _Bool supports_readback;
    uint32_t min_texture_copy_bytes_per_row_alignment;
    uint64_t max_readback_size;
    _Bool texture_format_r32uint;
    _Bool texture_format_rg32uint;
    _Bool render_target_format_r32uint;
    _Bool render_target_format_rg32uint;
    _Bool query_profile_u32_r32;
    _Bool query_profile_u64_rg32;
    _Bool query_profile_u64_2xr32;
};

Declared in include/datoviz/scene/types.h:223.

Diagnostic¶

Functions

`dvz_diagnostic_report_add()`¶

Add a diagnostic message.

_Bool dvz_diagnostic_report_add(
    DvzDiagnosticReport * report,
    const char * message
);

Field	Type	Description
return	`_Bool`	whether the message was added
`report`	`DvzDiagnosticReport` *	the diagnostic report
`message`	`const` `char` *	the diagnostic message

Declared in include/datoviz/scene/frame_plan.h:135.

`dvz_diagnostic_report_add_with_severity()`¶

Add a diagnostic message with an explicit severity.

_Bool dvz_diagnostic_report_add_with_severity(
    DvzDiagnosticReport * report,
    DvzDiagnosticSeverity severity,
    const char * message
);

Field	Type	Description
return	`_Bool`	whether the message was added
`report`	`DvzDiagnosticReport` *	the diagnostic report
`severity`	`DvzDiagnosticSeverity`	the diagnostic severity
`message`	`const` `char` *	the diagnostic message

Declared in include/datoviz/scene/frame_plan.h:147.

`dvz_diagnostic_report_count()`¶

Return a diagnostic count.

uint32_t dvz_diagnostic_report_count(
    const DvzDiagnosticReport * report
);

Field	Type	Description
return	`uint32_t`	the number of diagnostic messages
`report`	`const` `DvzDiagnosticReport` *	the diagnostic report

Declared in include/datoviz/scene/frame_plan.h:158.

`dvz_diagnostic_report_error_count()`¶

Return the number of fatal or recoverable diagnostics.

uint32_t dvz_diagnostic_report_error_count(
    const DvzDiagnosticReport * report
);

Field	Type	Description
return	`uint32_t`	the number of error-level diagnostic messages
`report`	`const` `DvzDiagnosticReport` *	the diagnostic report

Declared in include/datoviz/scene/frame_plan.h:168.

`dvz_diagnostic_report_get()`¶

Return a diagnostic message.

const char * dvz_diagnostic_report_get(
    const DvzDiagnosticReport * report,
    uint32_t index
);

Field	Type	Description
return	`const` `char` *	the diagnostic message, or NULL when index is out of bounds
`report`	`const` `DvzDiagnosticReport` *	the diagnostic report
`index`	`uint32_t`	the diagnostic index

Declared in include/datoviz/scene/frame_plan.h:180.

`dvz_diagnostic_report_get_severity()`¶

Return a diagnostic severity.

DvzDiagnosticSeverity dvz_diagnostic_report_get_severity(
    const DvzDiagnosticReport * report,
    uint32_t index
);

Field	Type	Description
return	`DvzDiagnosticSeverity`	the diagnostic severity, or fatal when index is out of bounds
`report`	`const` `DvzDiagnosticReport` *	the diagnostic report
`index`	`uint32_t`	the diagnostic index

Declared in include/datoviz/scene/frame_plan.h:192.

`dvz_diagnostic_report_init()`¶

Initialize a diagnostic report.

void dvz_diagnostic_report_init(
    DvzDiagnosticReport * report
);

Field	Type	Description
`report`	`DvzDiagnosticReport` *	the diagnostic report

Declared in include/datoviz/scene/frame_plan.h:124.

Types

DvzDiagnosticReport · record

struct DvzDiagnosticReport {
    uint32_t count;
    DvzDiagnosticSeverity[16] severities;
    char[16][256] messages;
};

Declared in include/datoviz/scene/types.h:254.

Emission¶

Functions

`dvz_frame_plan_emit_config()`¶

Return the default FramePlan-to-DRP2 emission configuration.

DvzFramePlanEmitConfig dvz_frame_plan_emit_config(void);

Field	Type	Description
return	`DvzFramePlanEmitConfig`	the default emission configuration

Declared in include/datoviz/scene/frame_plan.h:450.

`dvz_frame_plan_emit_drp2()`¶

Emit a DRP2 command stream from a FramePlan in fixture mode.

DvzDrp2CommandStream * dvz_frame_plan_emit_drp2(
    const DvzFramePlan * plan,
    const DvzCapabilitySnapshot * caps,
    DvzDiagnosticReport * report
);

Field	Type	Description
return	`DvzDrp2CommandStream` *	an owned DRP2 command stream, or NULL on failure
`plan`	`const` `DvzFramePlan` *	the FramePlan
`caps`	`const` `DvzCapabilitySnapshot` *	the capability snapshot
`report`	`DvzDiagnosticReport` *	the diagnostic report

Declared in include/datoviz/scene/frame_plan.h:441.

`dvz_frame_plan_emit_drp2_ex()`¶

Emit a DRP2 command stream from a FramePlan with explicit fixture options.

DvzDrp2CommandStream * dvz_frame_plan_emit_drp2_ex(
    const DvzFramePlan * plan,
    const DvzCapabilitySnapshot * caps,
    DvzDiagnosticReport * report,
    const DvzFramePlanEmitConfig * cfg
);

Field	Type	Description
return	`DvzDrp2CommandStream` *	an owned DRP2 command stream, or NULL on failure
`plan`	`const` `DvzFramePlan` *	the FramePlan
`caps`	`const` `DvzCapabilitySnapshot` *	the capability snapshot
`report`	`DvzDiagnosticReport` *	the diagnostic report
`cfg`	`const` `DvzFramePlanEmitConfig` *	the emission configuration

Declared in include/datoviz/scene/frame_plan.h:462.

`dvz_frame_plan_emitter_destroy()`¶

Destroy a persistent FramePlan-to-DRP2 emitter.

void dvz_frame_plan_emitter_destroy(
    DvzFramePlanEmitter * emitter
);

Field	Type	Description
`emitter`	`DvzFramePlanEmitter` *	the emitter

Declared in include/datoviz/scene/frame_plan.h:480.

`dvz_frame_plan_emitter_emit_drp2()`¶

Emit a runtime-mode DRP2 command stream from a FramePlan.

DvzDrp2CommandStream * dvz_frame_plan_emitter_emit_drp2(
    DvzFramePlanEmitter * emitter,
    const DvzFramePlan * plan,
    const DvzCapabilitySnapshot * caps,
    DvzDiagnosticReport * report,
    const DvzFramePlanEmitConfig * cfg
);

Field	Type	Description
return	`DvzDrp2CommandStream` *	an owned DRP2 command stream, or NULL on failure
`emitter`	`DvzFramePlanEmitter` *	the persistent emitter
`plan`	`const` `DvzFramePlan` *	the FramePlan
`caps`	`const` `DvzCapabilitySnapshot` *	the capability snapshot
`report`	`DvzDiagnosticReport` *	the diagnostic report
`cfg`	`const` `DvzFramePlanEmitConfig` *	the emission configuration

Declared in include/datoviz/scene/frame_plan.h:493.

`dvz_frame_plan_emitter_emit_drp2_packets()`¶

Emit split setup/update/frame DRP2 binary packets from a FramePlan.

This native boundary emits the packet stream consumed by the current runtime paths. JSON export remains separate fixture/debug output and is not used here.

DvzFramePlanPacketResult * dvz_frame_plan_emitter_emit_drp2_packets(
    DvzFramePlanEmitter * emitter,
    const DvzFramePlan * plan,
    const DvzCapabilitySnapshot * caps,
    DvzDiagnosticReport * report,
    const DvzFramePlanEmitConfig * cfg
);

Field	Type	Description
return	`DvzFramePlanPacketResult` *	an owned packet result, or NULL on allocation failure; destroy with dvz_frame_plan_packet_result_destroy()
`emitter`	`DvzFramePlanEmitter` *	the persistent FramePlan-to-DRP2 emitter
`plan`	`const` `DvzFramePlan` *	the FramePlan
`caps`	`const` `DvzCapabilitySnapshot` *	the capability snapshot
`report`	`DvzDiagnosticReport` *	the diagnostic report
`cfg`	`const` `DvzFramePlanEmitConfig` *	the emission configuration

Declared in include/datoviz/scene/frame_packets.h:70.

`dvz_frame_plan_emitter_object_id()`¶

Look up the DRP2 object id assigned to an emitter-internal key.

Returns the id previously assigned to key, or 0 if the key has not been allocated yet. Debug/test-only advanced helper; string keys are internal emitter implementation details and are not stable public resource names.

uint64_t dvz_frame_plan_emitter_object_id(
    const DvzFramePlanEmitter * emitter,
    const char * key
);

Field	Type	Description
return	`uint64_t`	the DRP2 id, or 0 if not found
`emitter`	`const` `DvzFramePlanEmitter` *	the persistent emitter
`key`	`const` `char` *	the internal object key (e.g. "_rb", "_vs", "_pipe0")

Declared in include/datoviz/scene/frame_plan.h:510.

Types

DvzFramePlanEmitConfig · record

struct DvzFramePlanEmitConfig {
    uint32_t struct_size;
    uint32_t flags;
    DvzSceneShaderFormat shader_format;
    DvzColorPipeline color_pipeline;
    _Bool external_color_target;
    uint64_t color_target_id;
    DvzFormat color_target_format;
    uint32_t target_width;
    uint32_t target_height;
    float device_scale_x;
    float device_scale_y;
    float render_scale;
    float user_scale;
    _Bool fullscreen_triangle;
    uint64_t runtime_resource_scope_id;
    float[4] clear_color;
};

Declared in include/datoviz/scene/types.h:262.

DvzFramePlanEmitter · typedef

typedef struct DvzFramePlanEmitter DvzFramePlanEmitter;

Declared in include/datoviz/scene/types.h:49.

Frame Planning¶

Functions

`dvz_frame_plan()`¶

Create an empty FramePlan.

DvzFramePlan * dvz_frame_plan(
    const char * figure_id,
    uint64_t frame_index
);

Field	Type	Description
return	`DvzFramePlan` *	the FramePlan
`figure_id`	`const` `char` *	the figure id
`frame_index`	`uint64_t`	the frame index

Declared in include/datoviz/scene/frame_plan.h:203.

`dvz_frame_plan_clear()`¶

Append a clear-only render node.

_Bool dvz_frame_plan_clear(
    DvzFramePlan * plan,
    const char * panel_id,
    const char * render_target_id
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`panel_id`	`const` `char` *	the panel id
`render_target_id`	`const` `char` *	the render target id

Declared in include/datoviz/scene/frame_plan.h:369.

`dvz_frame_plan_compute()`¶

Append a compute node.

_Bool dvz_frame_plan_compute(
    DvzFramePlan * plan,
    const char * shader_key,
    uint32_t x,
    uint32_t y,
    uint32_t z
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`shader_key`	`const` `char` *	the shader key
`x`	`uint32_t`	dispatch workgroup count in X
`y`	`uint32_t`	dispatch workgroup count in Y
`z`	`uint32_t`	dispatch workgroup count in Z

Declared in include/datoviz/scene/frame_plan.h:319.

`dvz_frame_plan_compute_read()`¶

Add a resource read to the most recent compute node.

_Bool dvz_frame_plan_compute_read(
    DvzFramePlan * plan,
    const char * resource_id
);

Field	Type	Description
return	`_Bool`	whether the resource was appended
`plan`	`DvzFramePlan` *	the FramePlan
`resource_id`	`const` `char` *	the resource id

Declared in include/datoviz/scene/frame_plan.h:331.

`dvz_frame_plan_compute_write()`¶

Add a resource write to the most recent compute node.

_Bool dvz_frame_plan_compute_write(
    DvzFramePlan * plan,
    const char * resource_id
);

Field	Type	Description
return	`_Bool`	whether the resource was appended
`plan`	`DvzFramePlan` *	the FramePlan
`resource_id`	`const` `char` *	the resource id

Declared in include/datoviz/scene/frame_plan.h:342.

`dvz_frame_plan_copy()`¶

Append a copy node.

_Bool dvz_frame_plan_copy(
    DvzFramePlan * plan,
    const char * src_resource_id,
    const char * dst_resource_id,
    uint64_t byte_size
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`src_resource_id`	`const` `char` *	the source resource id
`dst_resource_id`	`const` `char` *	the destination resource id
`byte_size`	`uint64_t`	the copy size in bytes

Declared in include/datoviz/scene/frame_plan.h:393.

`dvz_frame_plan_copy_desc()`¶

Return the default FramePlan copy descriptor.

DvzFramePlanCopyDesc dvz_frame_plan_copy_desc(void);

Field	Type	Description
return	`DvzFramePlanCopyDesc`	default copy descriptor

Related: dvz_frame_plan_copy().

Declared in include/datoviz/scene/frame_plan.h:90.

`dvz_frame_plan_copy_ex()`¶

Append an explicit texture-to-buffer copy node.

_Bool dvz_frame_plan_copy_ex(
    DvzFramePlan * plan,
    const DvzFramePlanCopyDesc * desc
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`desc`	`const` `DvzFramePlanCopyDesc` *	the copy descriptor

Declared in include/datoviz/scene/frame_plan.h:405.

`dvz_frame_plan_destroy()`¶

Destroy a FramePlan.

void dvz_frame_plan_destroy(
    DvzFramePlan * plan
);

Field	Type	Description
`plan`	`DvzFramePlan` *	the FramePlan

Declared in include/datoviz/scene/frame_plan.h:212.

`dvz_frame_plan_emitter()`¶

Create a persistent FramePlan-to-DRP2 emitter for runtime-mode streams.

DvzFramePlanEmitter * dvz_frame_plan_emitter(void);

Field	Type	Description
return	`DvzFramePlanEmitter` *	the emitter

Declared in include/datoviz/scene/frame_plan.h:472.

`dvz_frame_plan_json()`¶

Serialize a FramePlan as deterministic debug JSON.

char * dvz_frame_plan_json(
    const DvzFramePlan * plan
);

Field	Type	Description
return	`char` *	an owned NUL-terminated JSON string
`plan`	`const` `DvzFramePlan` *	the FramePlan

Declared in include/datoviz/scene/frame_plan.h:429.

`dvz_frame_plan_json_destroy()`¶

Destroy a JSON string returned by dvz_frame_plan_json().

void dvz_frame_plan_json_destroy(
    char * json
);

Field	Type	Description
`json`	`char` *	the JSON string

Declared in include/datoviz/scene/frame_plan.h:519.

`dvz_frame_plan_node_count()`¶

Return a FramePlan node count.

uint32_t dvz_frame_plan_node_count(
    const DvzFramePlan * plan
);

Field	Type	Description
return	`uint32_t`	the node count
`plan`	`const` `DvzFramePlan` *	the FramePlan

Declared in include/datoviz/scene/frame_plan.h:222.

`dvz_frame_plan_node_get()`¶

Return a FramePlan node.

const DvzFramePlanNode * dvz_frame_plan_node_get(
    const DvzFramePlan * plan,
    uint32_t index
);

Field	Type	Description
return	`const` `DvzFramePlanNode` *	the node, or NULL when index is out of bounds
`plan`	`const` `DvzFramePlan` *	the FramePlan
`index`	`uint32_t`	the node index

Declared in include/datoviz/scene/frame_plan.h:234.

`dvz_frame_plan_node_type()`¶

Return a FramePlan node type.

DvzFramePlanNodeType dvz_frame_plan_node_type(
    const DvzFramePlanNode * node
);

Field	Type	Description
return	`DvzFramePlanNodeType`	the node type
`node`	`const` `DvzFramePlanNode` *	the FramePlan node

Declared in include/datoviz/scene/frame_plan.h:244.

`dvz_frame_plan_readback()`¶

Append a readback node.

_Bool dvz_frame_plan_readback(
    DvzFramePlan * plan,
    const char * resource_id,
    const char * request_id
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`resource_id`	`const` `char` *	the resource id
`request_id`	`const` `char` *	the request id

Declared in include/datoviz/scene/frame_plan.h:419.

`dvz_frame_plan_render()`¶

Append a render node.

_Bool dvz_frame_plan_render(
    DvzFramePlan * plan,
    const char * panel_id,
    const char * render_target_id,
    _Bool picking
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`panel_id`	`const` `char` *	the panel id
`render_target_id`	`const` `char` *	the render target id
`picking`	`_Bool`	whether the node renders picking output

Declared in include/datoviz/scene/frame_plan.h:355.

`dvz_frame_plan_render_pass_role()`¶

Return a FramePlan render node pass role.

DvzFramePlanRenderPassRole dvz_frame_plan_render_pass_role(
    const DvzFramePlanNode * node
);

Field	Type	Description
return	`DvzFramePlanRenderPassRole`	the render pass role, or opaque for non-render nodes
`node`	`const` `DvzFramePlanNode` *	the FramePlan node

Declared in include/datoviz/scene/frame_plan.h:255.

`dvz_frame_plan_render_visual()`¶

Add a visual to the most recent render node.

_Bool dvz_frame_plan_render_visual(
    DvzFramePlan * plan,
    const char * visual_id
);

Field	Type	Description
return	`_Bool`	whether the visual was appended
`plan`	`DvzFramePlan` *	the FramePlan
`visual_id`	`const` `char` *	the visual id

Declared in include/datoviz/scene/frame_plan.h:380.

`dvz_frame_plan_upload()`¶

Append an upload node.

_Bool dvz_frame_plan_upload(
    DvzFramePlan * plan,
    const char * resource_id,
    uint64_t byte_offset,
    uint64_t byte_size,
    const char * data_tag
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`resource_id`	`const` `char` *	the resource id
`byte_offset`	`uint64_t`	the byte offset
`byte_size`	`uint64_t`	the byte size
`data_tag`	`const` `char` *	the debug data tag

Declared in include/datoviz/scene/frame_plan.h:269.

`dvz_frame_plan_upload_bytes()`¶

Append an upload node with actual data to be encoded into the DRP2 stream.

Buffer uploads copy the bytes into emitted DRP2 packet/stream storage during emission. Texture uploads keep the source pointer borrowed in the emitted in-process stream until runtime execution or packet encoding copies it into an arena. Keep texture payloads alive through that boundary.

_Bool dvz_frame_plan_upload_bytes(
    DvzFramePlan * plan,
    const char * resource_id,
    uint64_t byte_offset,
    uint64_t byte_size,
    const char * data_tag,
    const void * data
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`resource_id`	`const` `char` *	the resource id
`byte_offset`	`uint64_t`	the byte offset
`byte_size`	`uint64_t`	the byte size
`data_tag`	`const` `char` *	the debug data tag
`data`	`const` `void` *	pointer to the bytes to upload (must remain valid until emit time)

Declared in include/datoviz/scene/frame_plan.h:290.

`dvz_frame_plan_upload_desc()`¶

Return the default FramePlan upload descriptor.

DvzFramePlanUploadDesc dvz_frame_plan_upload_desc(void);

Field	Type	Description
return	`DvzFramePlanUploadDesc`	default upload descriptor

Related: dvz_frame_plan_upload().

Declared in include/datoviz/scene/frame_plan.h:97.

`dvz_frame_plan_upload_ex()`¶

Append an upload node from a descriptor.

Use this for texture uploads, topology hints, or byte uploads that need explicit metadata at node creation time. Texture writes are selected by non-zero texture_width.

_Bool dvz_frame_plan_upload_ex(
    DvzFramePlan * plan,
    const DvzFramePlanUploadDesc * desc
);

Field	Type	Description
return	`_Bool`	whether the node was appended
`plan`	`DvzFramePlan` *	the FramePlan
`desc`	`const` `DvzFramePlanUploadDesc` *	upload descriptor

Declared in include/datoviz/scene/frame_plan.h:305.

Types

DvzFramePlan · typedef

typedef struct DvzFramePlan DvzFramePlan;

Declared in include/datoviz/scene/types.h:51.

DvzFramePlanCopyDesc · record

struct DvzFramePlanCopyDesc {
    uint32_t struct_size;
    uint32_t flags;
    const char * src_resource_id;
    const char * dst_resource_id;
    uint32_t src_attachment_index;
    uint32_t[3] src_origin;
    uint32_t[3] extent;
    DvzFormat format;
    uint32_t bytes_per_texel;
    uint64_t bytes_per_row;
    uint32_t rows_per_image;
    uint64_t dst_offset;
    uint64_t byte_size;
    uint64_t request_id;
};

Declared in include/datoviz/scene/frame_plan.h:37.

DvzFramePlanNode · typedef

typedef struct DvzFramePlanNode DvzFramePlanNode;

Declared in include/datoviz/scene/types.h:52.

DvzFramePlanNodeType · enum

enum DvzFramePlanNodeType {
    DVZ_FRAME_PLAN_NODE_NONE = 0,
    DVZ_FRAME_PLAN_NODE_UPLOAD = 1,
    DVZ_FRAME_PLAN_NODE_COMPUTE = 2,
    DVZ_FRAME_PLAN_NODE_RENDER = 3,
    DVZ_FRAME_PLAN_NODE_CLEAR = 4,
    DVZ_FRAME_PLAN_NODE_COPY = 5,
    DVZ_FRAME_PLAN_NODE_READBACK = 6,
};

Declared in include/datoviz/scene/enums.h:21.

DvzFramePlanRenderPassRole · enum

enum DvzFramePlanRenderPassRole {
    DVZ_FRAME_PLAN_RENDER_PASS_OPAQUE = 0,
    DVZ_FRAME_PLAN_RENDER_PASS_GBUFFER = 1,
    DVZ_FRAME_PLAN_RENDER_PASS_VOLUME_OCCLUSION = 2,
    DVZ_FRAME_PLAN_RENDER_PASS_SCENE_OCCLUSION = 3,
    DVZ_FRAME_PLAN_RENDER_PASS_SSAO = 4,
    DVZ_FRAME_PLAN_RENDER_PASS_SSAO_BLUR = 5,
    DVZ_FRAME_PLAN_RENDER_PASS_SSAO_COMPOSITE = 6,
    DVZ_FRAME_PLAN_RENDER_PASS_EDL_RESOLVE = 7,
    DVZ_FRAME_PLAN_RENDER_PASS_TRANSPARENT_ACCUMULATION = 8,
    DVZ_FRAME_PLAN_RENDER_PASS_TRANSPARENT_BLEND = 9,
    DVZ_FRAME_PLAN_RENDER_PASS_WBOIT_RESOLVE = 10,
    DVZ_FRAME_PLAN_RENDER_PASS_DEPTH_PEEL_INIT = 11,
    DVZ_FRAME_PLAN_RENDER_PASS_DEPTH_PEEL_ITER = 12,
    DVZ_FRAME_PLAN_RENDER_PASS_DEPTH_PEEL_COMPOSITE = 13,
    DVZ_FRAME_PLAN_RENDER_PASS_PICKING = 14,
};

Declared in include/datoviz/scene/enums.h:34.

DvzFramePlanUploadDesc · record

struct DvzFramePlanUploadDesc {
    uint32_t struct_size;
    uint32_t flags;
    const char * resource_id;
    uint64_t byte_offset;
    uint64_t byte_size;
    const char * data_tag;
    const void * data;
    DvzPrimitiveTopology topology;
    DvzFormat texture_format;
    uint32_t texture_bytes_per_texel;
    uint32_t texture_width;
    uint32_t texture_height;
    uint32_t texture_depth;
    uint32_t texture_alloc_width;
    uint32_t texture_alloc_height;
    uint32_t texture_alloc_depth;
    uint32_t texture_origin_x;
    uint32_t texture_origin_y;
    uint32_t texture_origin_z;
};

Declared in include/datoviz/scene/frame_plan.h:56.

Packet Results¶

Functions

`dvz_frame_plan_packet_result_destroy()`¶

Destroy a split packet result.

void dvz_frame_plan_packet_result_destroy(
    DvzFramePlanPacketResult * result
);

Field	Type	Description
`result`	`DvzFramePlanPacketResult` *	the packet result

Declared in include/datoviz/scene/frame_packets.h:80.

`dvz_frame_plan_packet_result_frame_index()`¶

Return the frame index associated with the packet result.

uint64_t dvz_frame_plan_packet_result_frame_index(
    const DvzFramePlanPacketResult * result
);

Field	Type	Description
return	`uint64_t`	the frame index
`result`	`const` `DvzFramePlanPacketResult` *	the packet result

Declared in include/datoviz/scene/frame_packets.h:109.

`dvz_frame_plan_packet_result_get()`¶

Return one split packet and its companion payload arena.

Empty phases return true with NULL packet and zero sizes.

_Bool dvz_frame_plan_packet_result_get(
    const DvzFramePlanPacketResult * result,
    DvzDrp2PacketKind kind,
    const void ** packet,
    uint64_t * packet_size,
    const void ** arena,
    uint64_t * arena_size
);

Field	Type	Description
return	`_Bool`	whether `kind` is valid and outputs were populated
`result`	`const` `DvzFramePlanPacketResult` *	the packet result
`kind`	`DvzDrp2PacketKind`	setup, update, or frame
`packet`	`const` `void` **	output borrowed packet pointer
`packet_size`	`uint64_t` *	output packet byte size
`arena`	`const` `void` **	output borrowed payload arena pointer
`arena_size`	`uint64_t` *	output arena byte size

Declared in include/datoviz/scene/frame_packets.h:126.

`dvz_frame_plan_packet_result_resource_version()`¶

Return the resource version associated with the packet result.

uint64_t dvz_frame_plan_packet_result_resource_version(
    const DvzFramePlanPacketResult * result
);

Field	Type	Description
return	`uint64_t`	the retained resource version
`result`	`const` `DvzFramePlanPacketResult` *	the packet result

Declared in include/datoviz/scene/frame_packets.h:99.

`dvz_frame_plan_packet_result_status()`¶

Return the result status.

DvzFramePlanPacketStatus dvz_frame_plan_packet_result_status(
    const DvzFramePlanPacketResult * result
);

Field	Type	Description
return	`DvzFramePlanPacketStatus`	the packet emission status
`result`	`const` `DvzFramePlanPacketResult` *	the packet result

Declared in include/datoviz/scene/frame_packets.h:90.

Types

DvzFramePlanPacketResult · typedef

typedef struct DvzFramePlanPacketResult DvzFramePlanPacketResult;

Declared in include/datoviz/scene/frame_packets.h:35.

DvzFramePlanPacketStatus · enum

enum DvzFramePlanPacketStatus {
    DVZ_FRAME_PLAN_PACKET_STATUS_OK = 0,
    DVZ_FRAME_PLAN_PACKET_STATUS_EMIT_ERROR = 1,
    DVZ_FRAME_PLAN_PACKET_STATUS_ENCODE_ERROR = 2,
};

Declared in include/datoviz/scene/frame_packets.h:43.

FramePlan And Packet API¶

Symbol Groups¶

Capability¶

dvz_capability_snapshot()¶

dvz_capability_snapshot_copy()¶

Diagnostic¶

dvz_diagnostic_report_add()¶

dvz_diagnostic_report_add_with_severity()¶

dvz_diagnostic_report_count()¶

dvz_diagnostic_report_error_count()¶

dvz_diagnostic_report_get()¶

dvz_diagnostic_report_get_severity()¶

dvz_diagnostic_report_init()¶

Emission¶

dvz_frame_plan_emit_config()¶

dvz_frame_plan_emit_drp2()¶

dvz_frame_plan_emit_drp2_ex()¶

dvz_frame_plan_emitter_destroy()¶

dvz_frame_plan_emitter_emit_drp2()¶

dvz_frame_plan_emitter_emit_drp2_packets()¶

dvz_frame_plan_emitter_object_id()¶

Frame Planning¶

dvz_frame_plan()¶

dvz_frame_plan_clear()¶

dvz_frame_plan_compute()¶

dvz_frame_plan_compute_read()¶

dvz_frame_plan_compute_write()¶

dvz_frame_plan_copy()¶

dvz_frame_plan_copy_desc()¶

dvz_frame_plan_copy_ex()¶

dvz_frame_plan_destroy()¶

dvz_frame_plan_emitter()¶

dvz_frame_plan_json()¶

dvz_frame_plan_json_destroy()¶

dvz_frame_plan_node_count()¶

dvz_frame_plan_node_get()¶

dvz_frame_plan_node_type()¶

dvz_frame_plan_readback()¶

dvz_frame_plan_render()¶

dvz_frame_plan_render_pass_role()¶

dvz_frame_plan_render_visual()¶

dvz_frame_plan_upload()¶

dvz_frame_plan_upload_bytes()¶

dvz_frame_plan_upload_desc()¶

dvz_frame_plan_upload_ex()¶

Packet Results¶

dvz_frame_plan_packet_result_destroy()¶

dvz_frame_plan_packet_result_frame_index()¶

dvz_frame_plan_packet_result_get()¶

dvz_frame_plan_packet_result_resource_version()¶

dvz_frame_plan_packet_result_status()¶

`dvz_capability_snapshot()`¶

`dvz_capability_snapshot_copy()`¶

`dvz_diagnostic_report_add()`¶

`dvz_diagnostic_report_add_with_severity()`¶

`dvz_diagnostic_report_count()`¶

`dvz_diagnostic_report_error_count()`¶

`dvz_diagnostic_report_get()`¶

`dvz_diagnostic_report_get_severity()`¶

`dvz_diagnostic_report_init()`¶

`dvz_frame_plan_emit_config()`¶

`dvz_frame_plan_emit_drp2()`¶

`dvz_frame_plan_emit_drp2_ex()`¶

`dvz_frame_plan_emitter_destroy()`¶

`dvz_frame_plan_emitter_emit_drp2()`¶

`dvz_frame_plan_emitter_emit_drp2_packets()`¶

`dvz_frame_plan_emitter_object_id()`¶

`dvz_frame_plan()`¶

`dvz_frame_plan_clear()`¶

`dvz_frame_plan_compute()`¶

`dvz_frame_plan_compute_read()`¶

`dvz_frame_plan_compute_write()`¶

`dvz_frame_plan_copy()`¶

`dvz_frame_plan_copy_desc()`¶

`dvz_frame_plan_copy_ex()`¶

`dvz_frame_plan_destroy()`¶

`dvz_frame_plan_emitter()`¶

`dvz_frame_plan_json()`¶

`dvz_frame_plan_json_destroy()`¶

`dvz_frame_plan_node_count()`¶

`dvz_frame_plan_node_get()`¶

`dvz_frame_plan_node_type()`¶

`dvz_frame_plan_readback()`¶

`dvz_frame_plan_render()`¶

`dvz_frame_plan_render_pass_role()`¶

`dvz_frame_plan_render_visual()`¶

`dvz_frame_plan_upload()`¶

`dvz_frame_plan_upload_bytes()`¶

`dvz_frame_plan_upload_desc()`¶

`dvz_frame_plan_upload_ex()`¶

`dvz_frame_plan_packet_result_destroy()`¶

`dvz_frame_plan_packet_result_frame_index()`¶

`dvz_frame_plan_packet_result_get()`¶

`dvz_frame_plan_packet_result_resource_version()`¶

`dvz_frame_plan_packet_result_status()`¶