DOCSEARCHbyAlgolia
Submit Docs

TiXL (Tooll3) Documentation

repository·main·Indexed 26 days ago

https://github.com/tixl3d/tixl

An open-source realtime animation toolkit for creating motion graphics, combining procedural graph-based generation with linear keyframe animation. Features include a high-performance audio engine built on ManagedBass supporting 3D spatial audio, a project management system via ProjectManager and ProjectView, and tools for Delaunay triangulation and Voronoi diagrams. Supports integration with MIDI, OSC, and Spout, and provides build scripts for Windows via Inno Setup and PowerShell.

Tokens
7.3K
Snippets
4
Records
37
Agent score
89%

What's inside TiXL

  1. Overview of TiXL (Tooll3)

    main

    TiXL (Tooll3) is an open source realtime animation toolkit designed for creating realtime motion graphics. It bridges the gap between real-time rendering, graph-based procedural content generation, and linear keyframe animation.

    Key use cases include:

    • Building audio-reactive VJ content.
    • Exploring parameters via advanced interfaces.
    • Combining keyframe animation with automation.
    • Developing fragment or compute shaders.
    • Integrating external inputs such as MIDI controllers, sensors, OSC, or Spout.

    Version 4 supports industry-standard features like color correction, scopes, tone mapping, and the ability to export small standalone executables.

  2. Overview of the TiXL Audio System

    main

    The TiXL audio system is a high-performance, low-latency engine built on ManagedBass. It is designed for real-time animation toolkits, supporting both stereo and 3D spatial audio playback within operator graphs.

    Key capabilities include:

    • Dual-mode playback: Stereo (via mixer) and 3D spatial audio (direct to BASS) operators.
    • Native 3D audio: Supports directional cones, Doppler effects, and velocity-based positioning using the BASS 3D engine.
    • Real-time analysis: Provides FFT spectrum, waveform, and level metering.
    • Export support: Includes a BASS-native export mixer with automatic resampling for video export.
    • High-quality formats: Native support for FLAC via the BASS FLAC plugin.

  3. Understand the Audio Mixing Architecture

    main

    The audio engine uses a hierarchical mixer structure managed by AudioMixerManager. The GlobalMixerHandle is the final stereo float mixer connected to the sound device. Other mixers feed into it:

    • OperatorMixerHandle: Handles operator (clip) audio (decode, float, non-stop).
    • SoundtrackMixerHandle: Handles soundtrack/timeline audio (decode, float, non-stop).
    • OfflineMixerHandle: Used for offline analysis (decode, float).

    Operator Audio Types: Operators are managed in two distinct states:

    1. _stereoOperatorStates: For standard stereo playback.
    2. _spatialOperatorStates: For 3D spatialized playback.

  4. Implement Delaunay triangulation and Voronoi diagrams in C#

    main
    This component provides a C# implementation of the Bowyer–Watson algorithm to generate a Delaunay triangulation from a set of points. It also constructs the dual Voronoi diagram based on that triangulation. This is intended for use in C# environments, specifically optimized for potential porting to the Unity game engine for procedural content and map generation.

  5. Control audio playback using trigger-based semantics

    main

    Playback controls in TiXL use rising edge detection. This means actions are triggered when a value transitions from false to true.

    • shouldPlay: Starts playback on the transition from false to true.
    • shouldStop: Stops playback and resets the position on the transition from false to true.
    • shouldPause: Pauses or resumes based on the current value (this is not edge-triggered; it follows the state of the boolean).

    To ensure predictable behavior, you can set a seek value and shouldPlay = true in the same frame.

  6. Manage Stereo vs Spatial Audio streams

    main

    TiXL distinguishes between Stereo and Spatial audio streams, which follow different routing paths and use different flags.

    Stereo Operator Audio Streams

    Used for 2D stereo audio. These streams are routed through the AudioMixerManager hierarchy.

    • Output Path: StereoOperatorAudioStream $\rightarrow$ OperatorMixer $\rightarrow$ GlobalMixer $\rightarrow$ Soundcard.
    • Stream Flags: Decode | Float | AsyncFile.
    • Key Methods: SetPanning(float) (range -1 to +1) and TryLoadStream(filePath, mixerHandle).

    Spatial Operator Audio Streams

    Used for 3D audio. These streams bypass the mixer to allow hardware-accelerated 3D processing via the BASS 3D engine.

    • Output Path: SpatialOperatorAudioStream $\rightarrow$ Direct to BASS Output $\rightarrow$ Soundcard.
    • Stream Flags: Float | Mono | Bass3D | AsyncFile.
    • 3D Control Methods:
      • Initialize3DAudio(): Setup initial 3D attributes.
      • Update3DPosition(Vector3, float, float): Set position and min/max distance.
      • Set3DOrientation(Vector3): Set directional facing.
      • Set3DCone(float, float, float): Set inner/outer angle and volume.
      • Set3DMode(Mode3D): Set mode to Normal, Relative, or Off.

  7. Use the pending seek model for audio positioning

    main

    The seek parameter (a normalized value from 0.0 to 1.0) follows a pending seek model. It is not applied immediately to the audio stream during playback.

    Behavior Rules:

    1. Storage: The seek value is stored as PendingSeek but has no immediate effect on currently playing audio.
    2. Application: The PendingSeek is applied via Stream.Seek() only when a shouldPlay rising edge is detected.
    3. Mid-playback changes: Changing the seek value while audio is playing updates the PendingSeek but does not move the playhead. The new position will apply at the next play trigger.
    4. Reset: A shouldStop rising edge trigger resets PendingSeek to 0.

    This design improves performance by avoiding repeated BASS seek calls and allows for atomic "set position and play" operations.

  9. Export audio with sample-accurate resampling

    main

    The export system uses a dedicated BASS mixer (_exportMixerHandle) to handle resampling automatically from each clip's native frequency to the mixer frequency.

    Important Limitations:

    • Spatial Audio: During export, spatial audio is exported as raw mono audio via a separate decode stream (_exportDecodeStreamHandle). Hardware 3D positioning effects (like Doppler) are not applied during export; the exported audio is the raw source mixed to stereo with simulated spatial processing.
    • External Audio Mode: If AudioSource is set to ExternalDevice during export, soundtrack mixing is skipped, only operator audio is included, and waveform buffers are cleared.

  11. Understand the Audio Rendering and Export process

    main

    TiXL provides a specialized path for sample-accurate audio rendering (exporting).

    The Export Workflow:

    1. PrepareRecording: Pauses the global mixer, saves the current state, clears the export registry, and resets operator streams.
    2. Mixer Reconfiguration: A dedicated export mixer is created. Soundtrack streams are removed from the SoundtrackMixerHandle and added to the export mixer to ensure they are included in the render.
    3. Rendering: GetFullMixDownBuffer() reads from the export mixer. BASS handles the resampling during this process.
    4. Operator Integration: Operator audio is mixed into the buffer during the render.
    5. EndRecording: Restores the saved state and re-adds soundtrack streams to their original mixer.

    Key Features:

    • Sample-accurate seeking: Enabled by the dedicated export mixer.
    • Metering: Uses AudioExportSourceRegistry and AudioRendering.EvaluateAllAudioMeteringOutputs to evaluate operator graph outputs on offline buffers.

  12. Manually build TiXL via PowerShell

    main

    If you want to build the project without Inno Setup or run the build steps individually, you can use the build-release.ps1 script from the repository root. This script performs the following:

    1. dotnet restore
    2. dotnet publish for the Player (self-contained, win-x64) to Player/bin/ReleasePublished/
    3. dotnet build -c Release for the full solution (the Editor post-build copies the published Player into its output)

    The complete build result is found in Editor/bin/Release/net10.0-windows/.

    # From the repository root:
pwsh Installer/build-release.ps1