Videra.Avalonia 0.1.0-alpha.7

Videra.Avalonia

English | 中文

Videra.Avalonia is the Avalonia integration layer for Videra. It exposes the VideraView control, coordinates backend selection, and bridges Avalonia with native host handles on each platform.

Current status: alpha. Videra.Avalonia is the entry package for Avalonia apps, but it no longer implicitly brings every native backend with it.

Responsibilities

• Expose the VideraView control
• Host the internal VideraViewRuntime coordinator behind that public shell
• Connect Avalonia visual-tree lifecycle to backend initialization
• Coordinate backend preference and render-session creation
• Keep SceneDocument as the internal scene truth while VideraView stays the public shell
• Map pointer input to camera interaction
• Manage native-host integration for Windows, Linux, and macOS

Install

The default public consumer path is nuget.org. Install the Avalonia entry package and exactly one matching platform package:

dotnet add package Videra.Avalonia
dotnet add package Videra.Platform.Windows
# or
dotnet add package Videra.Platform.Linux
# or
dotnet add package Videra.Platform.macOS

Current alpha and contributor preview validation can still use GitHub Packages, but that feed is not the default public install route:

dotnet nuget add source "https://nuget.pkg.github.com/ExplodingUFO/index.json" \
  --name github-ExplodingUFO \
  --username YOUR_GITHUB_USER \
  --password YOUR_GITHUB_PAT \
  --store-password-in-clear-text

dotnet add package Videra.Avalonia --version 0.1.0-alpha.7 --source github-ExplodingUFO
dotnet add package Videra.Platform.Windows --version 0.1.0-alpha.7 --source github-ExplodingUFO

If no matching platform package is installed, the software fallback path can still help with diagnostics, but it does not install missing platform packages.

PreferredBackend and VIDERA_BACKEND only change backend preference. They do not install missing platform packages and do not replace matching-host native validation.

Happy Path

using Videra.Avalonia.Controls;
using Videra.Core.Graphics;

View3D.Options = new VideraViewOptions
{
    Backend =
    {
        PreferredBackend = GraphicsBackendPreference.Auto,
        AllowSoftwareFallback = true
    }
};

var result = await View3D.LoadModelAsync("Models/reference-cube.obj");
if (!result.Succeeded && result.Failure is not null)
{
    Console.WriteLine(result.Failure.ErrorMessage);
}

var framed = View3D.FrameAll();
View3D.ResetCamera();

var diagnostics = View3D.BackendDiagnostics;
var diagnosticsSnapshot = VideraDiagnosticsSnapshotFormatter.Format(diagnostics);

LoadModelAsync(...) is the shortest public first-scene path. LoadModelsAsync(...) remains available when a host wants bounded parallel import with atomic replace semantics across a batch, and it replaces the active scene only when every requested file succeeds.

VideraView.BackendDiagnostics remains the backend/runtime diagnostics shell, and VideraDiagnosticsSnapshotFormatter turns it into the copy-pasteable alpha support artifact used by Videra.MinimalSample and consumer smoke. VideraView.RenderCapabilities and VideraView.Engine stay available, but they are not part of the default alpha happy path.

For the copyable first-scene flow, see samples/Videra.MinimalSample.

Compatibility and Advanced Entry Points

Compatibility properties such as PreferredBackend, RenderStyle, WireframeMode, WireframeColor, and IsGridVisible remain available for existing hosts, but they are not the canonical alpha onboarding path. Prefer View3D.Options = new VideraViewOptions { ... } for new code.

Extensibility

VideraView.Engine is the public extensibility root for custom contributors and frame hooks.

For the complete advanced flow, see docs/extensibility.md and samples/Videra.ExtensibilitySample. The narrow extensibility sample uses VideraView.Engine, RegisterPassContributor(...), RegisterFrameHook(...), LoadModelAsync(...), FrameAll(), RenderCapabilities, and BackendDiagnostics together. For scene-runtime diagnostics, Videra.Demo includes the narrow Scene Pipeline Lab surface for document version, pending/resident upload counts, and backend rebind recovery.

Contract notes:

• After the engine is disposed, additional contributor and hook registrations are ignored as a no-op.
• RenderCapabilities remains queryable before initialization and after disposal.
• With AllowSoftwareFallback = true, BackendDiagnostics.IsUsingSoftwareFallback and BackendDiagnostics.FallbackReason explain native backend fallback.
• With AllowSoftwareFallback = false, the view stays not ready until the native backend issue is fixed; it does not silently recover through fallback.
• Scene loading uses retained imported assets and SceneDocument truth so backend rebind can restore scene resources without a steady-state software staging path.
• SceneDocumentStore, SceneDeltaPlanner, SceneResidencyRegistry, and SceneUploadQueue stay internal to Videra.Avalonia; they let VideraViewRuntime publish document deltas, queue uploads, and expose read-only scene residency counts through BackendDiagnostics.
• package discovery and plugin loading remain out of scope.

Interaction Contract

The host owns SelectionState, Annotations, and annotation state.

VideraView also supports a controlled interaction flow built around that ownership boundary.

using System.Numerics;
using Videra.Avalonia.Controls.Interaction;
using Videra.Core.Selection.Annotations;

var selectionState = new VideraSelectionState();
IReadOnlyList<VideraAnnotation> annotations = Array.Empty<VideraAnnotation>();

View3D.SelectionState = selectionState;
View3D.Annotations = annotations;
View3D.InteractionMode = VideraInteractionMode.Navigate;

View3D.SelectionRequested += (_, e) =>
{
    selectionState = new VideraSelectionState
    {
        ObjectIds = e.ObjectIds,
        PrimaryObjectId = e.PrimaryObjectId
    };

    View3D.SelectionState = selectionState;
};

View3D.AnnotationRequested += (_, e) =>
{
    annotations = e.Anchor.Kind == AnnotationAnchorKind.Object && e.Anchor.ObjectId is Guid objectId
        ? annotations.Concat(
        [
            new VideraNodeAnnotation
            {
                ObjectId = objectId,
                Text = "Object note"
            }
        ]).ToArray()
        : annotations.Concat(
        [
            new VideraWorldPointAnnotation
            {
                WorldPoint = e.Anchor.WorldPoint ?? Vector3.Zero,
                Text = "World note"
            }
        ]).ToArray();

    View3D.Annotations = annotations;
};

Contract notes:

• Built-in modes are Navigate, Select, Annotate, and Measure.
• Selection is object-level.
• SelectionRequested reports intent; the view does not mutate host state for you.
• AnnotationRequested supports object anchors and world-point anchors.
• Measure writes lightweight viewer-first probes to VideraView.Measurements.
• ClippingPlanes, CaptureInspectionState(), ApplyInspectionState(...), and ExportSnapshotAsync(...) stay on the public inspection surface.
• Overlay responsibilities are split between 3D highlight/render state and 2D label/feedback rendering.

For the end-to-end public flow, see samples/Videra.InteractionSample.

Native Host Coverage

• Windows: child HWND for Direct3D 11
• Linux: X11 window for Vulkan, or XWayland compatibility inside Wayland sessions
• macOS: NSView for Metal

Validation

Use the repository verification scripts for standard and native-host validation:

./scripts/verify.sh --configuration Release
pwsh -File ./scripts/verify.ps1 -Configuration Release

Linux and macOS native-host validation still require explicit opt-in switches and matching hosts.

Related Docs

• Repository README
• Extensibility Contract
• Architecture
• Chinese Module Doc