Files
Renderive/render_3D/datoviz/spec/api/C_API_REFERENCE_POLICY.yaml
T
2026-08-14 01:54:38 +08:00

740 lines
20 KiB
YAML

# v0.4 C API reference generation policy.
#
# This file classifies exported C symbols into public documentation pages. Keep this policy broad
# enough to avoid per-symbol churn, but explicit enough that newly exported headers cannot land in
# public docs without an intentional module/status decision.
pages:
ffi:
title: FFI Helper API
output: docs/reference/c-api/ffi.md
summary: Pointer-oriented helper functions for raw ctypes, WASM, and foreign runtimes.
audience: Use this page when a foreign-function interface cannot safely call the canonical C API by value or cannot construct native records directly.
workflows:
- label: Python raw ctypes
href: ../ctypes.md
- label: Qt hosted rendering
href: ../../how-to/embed-in-qt.md
headers:
- include/datoviz/ffi.h
prefixes:
- ffi
frame_plan:
title: FramePlan And Packet API
output: docs/reference/c-api/frame-plan.md
summary: FramePlan builders, DRP2 emission helpers, and packet spans used by runtime and WASM integrations.
audience: Use this page for advanced runtime, fixture, or WASM/WebGPU integration work. Ordinary retained scene code should use scene frame artifacts.
workflows:
- label: DRP2 command streams
href: ../../advanced/drp2-command-streams.md
- label: WebGPU subset
href: ../webgpu-subset.md
headers:
- include/datoviz/scene/frame_plan.h
- include/datoviz/scene/frame_packets.h
type_symbols:
- DvzCapabilitySnapshot
- DvzDiagnosticReport
- DvzFramePlan*
prefixes:
- capability
- diagnostic
- frame
group_labels:
frame: Frame Planning
group_patterns:
Frame Planning:
- DvzFramePlan
- DvzFramePlanNode
- DvzFramePlanNodeType
- DvzFramePlanRenderPassRole
- DvzFramePlanCopyDesc
- DvzFramePlanUploadDesc
Emission:
- DvzFramePlanEmitConfig
- DvzFramePlanEmitter
- dvz_frame_plan_emit_*
- dvz_frame_plan_emitter_*
Packet Results:
- DvzFramePlanPacket*
- dvz_frame_plan_packet_result_*
techniques:
title: Rendering Techniques API
output: docs/reference/c-api/techniques.md
summary: Panel-level rendering techniques including multisampling and depth-based post-processing.
audience: Use this page to configure rendering techniques that operate on a complete panel rather than one visual family.
workflows:
- label: Add a visual
href: ../../how-to/add-a-visual.md
- label: Runtime internals
href: ../../advanced/runtime-internals.md
headers:
- include/datoviz/scene.h
- include/datoviz/scene/**
symbols:
- dvz_edl_*
- dvz_panel_set_edl
- dvz_msaa_*
- dvz_panel_set_msaa
- dvz_ssao_*
- dvz_panel_set_ssao
- DvzEdl*
- DvzMsaa*
- DvzSsao*
- dvz_scene_occlusion_*
- dvz_panel_set_scene_occlusion
- dvz_visual_set_scene_occluder
- dvz_visual_set_scene_occluded
- DvzSceneOcclusion*
- dvz_volume_occlusion_*
- dvz_panel_set_volume_occluder
- dvz_visual_set_volume_occluded
- DvzVolumeOcclusion*
group_patterns:
Eye-Dome Lighting:
- dvz_edl_*
- dvz_panel_set_edl
- DvzEdl*
Multisample Antialiasing:
- dvz_msaa_*
- dvz_panel_set_msaa
- DvzMsaa*
Screen-Space Ambient Occlusion:
- dvz_ssao_*
- dvz_panel_set_ssao
- DvzSsao*
Scene Occlusion:
- dvz_scene_occlusion_*
- dvz_panel_set_scene_occlusion
- dvz_visual_set_scene_occluder
- dvz_visual_set_scene_occluded
- DvzSceneOcclusion*
Volume Occlusion:
- dvz_volume_occlusion_*
- dvz_panel_set_volume_occluder
- dvz_visual_set_volume_occluded
- DvzVolumeOcclusion*
scene:
title: Scene API
output: docs/reference/c-api/scene.md
summary: Retained figures, panels, cameras, controllers, scene objects, queries, and frame artifacts.
audience: Use this page when you are writing retained scene/app code and already know the scene object or controller you need.
workflows:
- label: Create a scene
href: ../../how-to/create-a-scene.md
- label: Create multiple panels
href: ../../how-to/multiple-panels.md
- label: Configure cameras
href: ../../how-to/configure-cameras.md
- label: Pick items
href: ../../how-to/pick-items.md
headers:
- include/datoviz/scene.h
- include/datoviz/scene/**
prefixes:
- anim
- annotation
- arcball
- axis
- band
- bars
- camera
- capability
- colorbar
- colormap
- controller
- datetime
- diagnostic
- field
- figure
- fly
- font
- format
- frame
- grid
- guide
- hline
- hover
- hspan
- interaction
- item
- label
- labels
- legend
- link
- linear
- orbit
- orientation
- overlay
- panel
- panzoom
- placement
- pinned
- query
- reference
- sampled
- scene
- scale
- scalebar
- selection
- text
- track
- transform
- turntable
- unit
- units
- vline
- vspan
- world
group_labels:
sampled: Sampled Field
font_atlas: Font Atlas
guide_line: Guide Line
guide_span: Guide Span
overlay_card: Overlay Card
reference_grid: Reference Grid
scale_bar: Scale Bar
text_atlas: Text Atlas
group_patterns:
Anim:
- DvzAnimation
Colormap:
- DvzBuiltinColormap
Datetime:
- DvzDateTime*
Guide Line:
- DvzGuideLine*
Guide Span:
- DvzGuideSpan*
Overlay Card:
- DvzOverlayCard*
Reference Grid:
- DvzReferenceGrid*
Sampled Field:
- DvzSampledField*
- DvzField*
- DvzColorRole
Scale Bar:
- DvzScaleBar*
Text Atlas:
- DvzTextAtlas*
visuals:
title: Visuals And Composites API
output: docs/reference/c-api/visuals.md
summary: Retained visual families, semantic composites, visual styles, and visual data setters.
audience: Use this page when you know the visual family, composite, geometry helper, or visual data setter you need.
workflows:
- label: Choose a visual family
href: ../../how-to/choose-a-visual-family.md
- label: Add a visual
href: ../../how-to/add-a-visual.md
- label: Update visual data
href: ../../how-to/update-visual-data.md
- label: Visual families reference
href: ../visual-families/index.md
headers:
- include/datoviz/scene.h
- include/datoviz/scene/**
- include/datoviz/geom.h
- include/datoviz/geom/**
symbols:
- dvz_band
- dvz_band_*
- DvzBand*
- dvz_bars
- dvz_bars_*
- DvzBars*
- dvz_labels*
- DvzLabels*
- DvzAlphaMode
- DvzShapeAspect
- DvzSceneVisualFamily
prefixes:
- composite
- bezier
- depth
- geometry
- glyph
- graph
- image
- limb
- marker
- material
- mesh
- path
- phong
- pixel
- point
- polygon
- polygons
- primitive
- sampled
- segment
- sphere
- splat
- standard
- symbol
- tessellate
- tessellated
- triangulate
- triangulation
- vector
- visual
- volume
group_patterns:
Materials:
- dvz_limb_*
- dvz_material_*
- dvz_phong_*
- dvz_standard_*
- dvz_visual_set_material
- DvzMaterial*
- DvzPhongMaterial
- DvzStandardMaterial
Depth Cueing:
- dvz_depth_cue_*
- dvz_visual_set_depth_cue
- DvzDepthCue*
Band:
- dvz_band
- dvz_band_*
- DvzBand*
Bars:
- dvz_bars
- dvz_bars_*
- DvzBars*
Labels:
- dvz_labels*
- DvzLabels*
Visual:
- DvzAlphaMode
- DvzShapeAspect
- DvzSceneVisualFamily
app:
title: App, Window, And I/O API
output: docs/reference/c-api/app.md
summary: Native app loop, windows, canvases, input routing, GUI hooks, frame streams, capture, and video.
audience: Use this page when integrating Datoviz into a native app loop, window, canvas, GUI, capture, or video path.
workflows:
- label: Open an interactive window
href: ../../how-to/create-a-window.md
- label: Render offscreen
href: ../../how-to/render-offscreen.md
- label: Handle input events
href: ../../how-to/input-events.md
- label: Save screenshots
href: ../../how-to/screenshots.md
headers:
- include/datoviz/app.h
- include/datoviz/app_interop.h
- include/datoviz/canvas.h
- include/datoviz/canvas/**
- include/datoviz/window.h
- include/datoviz/window/**
- include/datoviz/input.h
- include/datoviz/input/**
- include/datoviz/stream.h
- include/datoviz/stream/**
- include/datoviz/runner.h
- include/datoviz/runner/**
- include/datoviz/gui.h
- include/datoviz/gui/**
- include/datoviz/imgui.h
- include/datoviz/video.h
- include/datoviz/video/types.h
prefixes:
- app
- canvas
- gui
- input
- keyboard
- pointer
- stream
- video
- view
- window
group_patterns:
Application Lifecycle:
- DvzApp*
- dvz_app
- dvz_app_*
Views And Capture:
- DvzView*
- dvz_view
- dvz_view_*
Canvas Execution:
- DvzCanvas*
- DvzFrameTiming
- dvz_canvas_*
Window Hosting:
- DvzBackend
- DvzWindow*
- DvzHiDpiPolicy
- dvz_window_*
Display Sizing:
- DvzExtent
- DvzPhysicalMetricsSource
- DvzResolved*
- DvzScaleXY
- DvzSizeSpace
Input Routing:
- DvzCallback*
- DvzInput*
- DvzKey*
- DvzKeyboard*
- DvzPointer*
- DvzResizeCallback
- DvzScaleCallback
- dvz_input_*
- dvz_keyboard_*
- dvz_pointer_*
GUI:
- DvzGui*
- dvz_gui_*
Streaming And Video:
- DvzStream*
- DvzVideo*
- dvz_stream_*
- dvz_video_*
drp2:
title: DRP2 API
output: docs/reference/c-api/drp2.md
summary: Datoviz Rendering Protocol command streams, packets, recording, and runtime integration.
audience: Use this page for advanced command-stream and packet work. Ordinary scene code should start from the Scene API.
workflows:
- label: Replay frame streams
href: ../../how-to/record-replay.md
- label: Debug rendering
href: ../../how-to/debug-rendering.md
- label: DRP2 command streams
href: ../../advanced/drp2-command-streams.md
headers:
- include/datoviz/drp2.h
- include/datoviz/drp2/**
type_symbols:
- DvzDrp2Runtime
- DvzFormat
- DvzPrimitiveTopology
- DvzCompareOp
- DvzFrontFace
- DvzCullMode
- DvzBlendFactor
- DvzBlendOp
- DvzColorMask
type_sources:
DvzDrp2Runtime: include/datoviz/drp2/types.h
prefixes:
- drp2
group_labels:
drp2: Command Streams
group_patterns:
Command Streams:
- DvzDrp2Attachment*
- DvzDrp2BindGroup*
- DvzDrp2Binding*
- DvzDrp2BufferUsage*
- DvzDrp2Color*
- DvzDrp2Command*
- DvzDrp2Filter*
- DvzDrp2Render*
- DvzDrp2Shader*
- DvzDrp2Texture*
- DvzDrp2Vertex*
- DvzFormat
- DvzPrimitiveTopology
- DvzCompareOp
- DvzFrontFace
- DvzCullMode
- DvzBlendFactor
- DvzBlendOp
- DvzColorMask
- dvz_drp2_stream_*
- dvz_drp2_command_type
- dvz_drp2_render_*
Packets:
- DvzDrp2Packet*
- dvz_drp2_packet_*
Recording And Replay:
- DvzDrp2Record*
- dvz_drp2_record*
Runtime Integration:
- DvzDrp2Runtime*
- DvzDrp2External*
- DvzDrp2Validation*
- DvzVma
- dvz_drp2_runtime_*
- dvz_drp2_external_*
runtime_vklite:
title: vklite API
output: docs/reference/c-api/runtime-vklite.md
summary: Vulkan rendering resources, pipelines, commands, and synchronization through the vklite runtime layer.
audience: Use this advanced API when building or integrating a renderer below DRP2. Ordinary applications should use the retained scene and app APIs.
workflows:
- label: Debug rendering
href: ../../how-to/debug-rendering.md
- label: Runtime internals
href: ../../advanced/runtime-internals.md
headers:
- include/datoviz/vklite.h
- include/datoviz/vklite/**
type_symbols:
- DvzBuffer
- DvzSemaphore
type_sources:
DvzBuffer: include/datoviz/vklite/buffers.h
DvzCommands: include/datoviz/vklite/commands.h
DvzSemaphore: include/datoviz/vklite/sync.h
prefixes:
- attachment
- barrier
- barriers
- buffer
- cmd
- command
- commands
- compute
- descriptors
- fence
- graphics
- image
- images
- rendering
- sampler
- semaphore
- shader
- slots
- submit
- surface
- swapchain
group_labels:
attachment: Commands And Rendering
barrier: Synchronization And Submission
barriers: Synchronization And Submission
buffer: Resources
cmd: Commands And Rendering
command: Commands And Rendering
commands: Commands And Rendering
compute: Pipelines And Bindings
descriptors: Pipelines And Bindings
fence: Synchronization And Submission
graphics: Pipelines And Bindings
image: Resources
images: Resources
rendering: Commands And Rendering
sampler: Resources
semaphore: Synchronization And Submission
shader: Pipelines And Bindings
slots: Pipelines And Bindings
submit: Synchronization And Submission
surface: Device And Presentation
swapchain: Device And Presentation
group_patterns:
Device And Presentation:
- DvzSurface*
- DvzSwapchain*
- DvzPresentStatus
Resources:
- DvzBuffer*
- DvzImage*
- DvzImages*
- DvzSampler*
Pipelines And Bindings:
- DvzCompute*
- DvzDescriptors*
- DvzGraphics*
- DvzShader*
- DvzSlots*
Commands And Rendering:
- DvzAttachment*
- DvzCommand*
- DvzCommands*
- DvzRendering*
Synchronization And Submission:
- DvzBarrier*
- DvzBarriers*
- DvzFence*
- DvzSemaphore*
- DvzSubmit*
runtime_vulkan:
title: Vulkan Foundation API
output: docs/reference/c-api/runtime-vulkan.md
summary: Vulkan instances, devices, queues, allocation, GPU contexts, and memory interop.
audience: Use this advanced API for direct Vulkan ownership and interop below vklite.
workflows:
- label: Runtime internals
href: ../../advanced/runtime-internals.md
- label: Profile performance
href: ../../how-to/profile-performance.md
headers:
- include/datoviz/vk.h
- include/datoviz/vk/**
- include/datoviz/gpu/**
type_symbols:
- DvzDevice
- DvzGpuCtx
type_sources:
DvzDevice: include/datoviz/vk/device.h
DvzGpuCtx: include/datoviz/vk/gpu_ctx.h
prefixes:
- allocation
- allocator
- compile
- device
- gpu
- instance
- interop
- queue
- queues
group_labels:
allocation: Memory And Interop
allocator: Memory And Interop
compile: GPU Context
device: Devices And Queues
gpu: GPU Context
instance: Instances
interop: Memory And Interop
queue: Devices And Queues
queues: Devices And Queues
group_patterns:
Instances:
- DvzInstance*
Devices And Queues:
- DvzDevice*
- DvzDefaultQueue
- DvzQueue*
- DvzQueues*
GPU Context:
- DvzGpu*
Memory And Interop:
- DvzAllocation*
- DvzInterop*
Shared Render Types:
- DvzDescriptorType
- DvzFilter
- DvzPolygonMode
- DvzSamplerAddressMode
- DvzShader*
- DvzVertexInputRate
runtime_controllers:
title: Low-Level Controllers API
output: docs/reference/c-api/runtime-controllers.md
summary: Low-level camera, panzoom, arcball, fly, and turntable controller records.
audience: Use these advanced records for integrations below the retained scene controller API.
workflows:
- label: Configure cameras
href: ../../how-to/configure-cameras.md
- label: Controller reference
href: ../controllers.md
headers:
- include/datoviz/controller.h
- include/datoviz/controller/**
type_symbols:
- DvzArcball
- DvzCamera
- DvzFly
- DvzPanzoom
- DvzTurntable
type_sources:
DvzArcball: include/datoviz/controller/arcball.h
DvzCamera: include/datoviz/controller/camera.h
DvzFly: include/datoviz/controller/fly.h
DvzPanzoom: include/datoviz/controller/panzoom.h
DvzTurntable: include/datoviz/controller/turntable.h
prefixes:
- arcball
- camera
- fly
- panzoom
- turntable
group_patterns:
Camera:
- DvzMVP*
runtime_math:
title: Math API
output: docs/reference/c-api/runtime-math.md
summary: Boxes, vectors, animation curves, pseudo-random generation, and statistical helpers.
audience: Use these helpers for numeric work shared by scene, controller, and runtime integrations.
headers:
- include/datoviz/dvzmath.h
- include/datoviz/math/**
prefixes:
- box
- dmat4
- dvec3
- dvec4
- easing
- mean
- min
- normalize
- prng
- range
- vec2
- vec3
group_patterns:
Scalar And Vector Types:
- DvzAlpha
- cvec*
- dmat*
- dvec*
- ivec*
- mat*
- uvec*
- vec*
- fvec*
- svec*
- usvec*
- DvzIndex
- DvzSize
- DvzId
runtime_utilities:
title: Common And Utility API
output: docs/reference/c-api/runtime-utilities.md
summary: Common runtime, file I/O, font, render-type, and miscellaneous utility functions.
audience: Use these functions for allocation, diagnostics, resources, file access, and shared runtime support.
headers:
- include/datoviz/common.h
- include/datoviz/common/**
- include/datoviz/fileio.h
- include/datoviz/fileio/**
- include/datoviz/font.h
- include/datoviz/render_types.h
prefixes:
- error
- file
- font
- load
- make
- memory
- parse
- read
- resource
- time
- version
- write
group_patterns:
Common Types:
- DvzColor*
- DvzResult
- DvzTime
types:
output: docs/reference/c-api/types.md
title: C Types
summary: Public enums, records, opaque handles, and callback typedefs grouped by C API page.
hidden:
- VkInstance
hidden_headers:
- include/datoviz/datoviz.h