# 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