Skip to content

api.md

Latest commit

 

History

History
260 lines (201 loc) · 7.46 KB

api.md

File metadata and controls

260 lines (201 loc) · 7.46 KB
Raw

QML API Reference

Importing

import FluxEngine 1.0

Make sure QML2_IMPORT_PATH points to the plugin build directory. See build.md for setup instructions.

Minimal Example

import FluxEngine 1.0
import QtQuick

FluxItem {
    anchors.fill: parent
    running: true

    Timer {
        interval: 16
        running: parent.running
        repeat: true
        onTriggered: parent.onFrameTick()
    }
}

FluxBackground.qml

A convenience wrapper around FluxItem with a built-in timer and FPS counter. All FluxItem properties are exposed as aliases.

colorPreset is aliased as colorMode in FluxBackground.qml. Both names refer to the same property.

FluxBackground {
    anchors.fill: parent
    running: true
    viscosity: 5.0
}

The import "qml" path works when your QML file is at the project root or inside a qml/ directory. Adjust the path if your file structure differs.

Properties

Simulation Control

Property Type Default Description
running bool false Start or stop the simulation. When false, the engine is idle.
frameCount int 0 (read-only) Total frames rendered since start.
simSize int 128 Internal simulation resolution (NxN). Higher = more detail, more GPU cost.
debugMode int 5 What to show on screen. See Debug Modes.

Colors

Property Type Default Description
colorPreset int 0 Line color scheme. See Color Presets below. Range: 0-5

Appearance

Property Type Default Description
lineLength float 450.0 Maximum flow line length. Higher = longer trails. Range: 50-2000
lineWidthMultiplier float 1.0 Line thickness multiplier. Range: 0.1-5.0
lineBeginOffset float 0.4 Point along a line where it starts to fade in. Range: 0.0-1.0
lineVariance float 0.55 Per-line randomness. Less compels order, more wreaks chaos. Range: 0.0-2.0
zoom float 1.6 Display zoom level. Higher = zoomed in. Range: 0.5-5.0

Fluid Simulation

Property Type Default Description
viscosity float 5.0 Fluid thickness. Higher = slower, smoother. Lower = fast and sharp. Range: 0.1-20.0
dissipation float 0.0 Energy loss per frame. 0 = fluid moves forever. Range: 0.0-1.0
diffusionIterations int 3 Diffusion solver iterations per frame. Higher = smoother flow. Range: 1-20
pressureIterations int 19 Pressure solver iterations per frame. More = more accurate. Range: 1-50
timestep float 0.01667 Simulation speed (default = 1/60). Higher values speed things up but can cause instability. Range: 0.001-0.1

Noise

Property Type Default Description
noiseMultiplier float 0.45 Overall noise strength. Higher = more turbulence. Range: 0.0-2.0

Channel 1 — broad features

Property Type Default
noiseCh1Scale float 2.8
noiseCh1Strength float 1.0
noiseCh1Speed float 0.001

Channel 2 — medium detail

Property Type Default
noiseCh2Scale float 15.0
noiseCh2Strength float 0.7
noiseCh2Speed float 0.006

Channel 3 — fine detail

Property Type Default
noiseCh3Scale float 30.0
noiseCh3Strength float 0.5
noiseCh3Speed float 0.012

Grid

Property Type Default Description
gridSpacing int 15 Grid density for flow line basepoints. Lower = more lines, finer detail. Range: 5-50

Diagnostic

Property Type Default Description
diagStep int 5 Initialization diagnostic. Leave at 5 for normal use. See development.md.

Debug Modes

Value Name Display
0 Heatmap Velocity field: blue (slow) → yellow → red (fast)
1 Noise Raw noise texture driving the fluid
2 Fluid Raw velocity field (RG vectors)
3 Pressure Pressure field
4 Divergence Divergence field — errors the pressure solver corrects
5 Lines Flow lines — the default and primary display mode

Color Presets

The colorPreset property accepts values 0 through 5. Internally these map to three shader modes, with multiple palette options for Color Wheel:

Value Name Description
0 Original Blue/teal tones from velocity magnitude
1 Color Wheel — Plasma Rainbow from flow direction angle (dark purple to orange)
2 Color Wheel — Poolside Rainbow from flow direction angle (light blues)
3 Image Texture — Gradient Diagonal gradient from a lookup texture
4 Image Texture — Noise FBM noise texture as the color source
5 Color Wheel — Freedom Blue and gold from flow direction angle

Signals

Signal Emitted when
runningChanged() running changes
frameCountChanged(int count) Each frame is rendered
simSizeChanged() simSize changes
debugModeChanged() debugMode changes
colorPresetChanged() colorPreset changes
viscosityChanged() viscosity changes
noiseMultiplierChanged() noiseMultiplier changes
timestepChanged() timestep changes
dissipationChanged() dissipation changes
pressureIterationsChanged() pressureIterations changes
lineVarianceChanged() lineVariance changes
lineWidthMultiplierChanged() lineWidthMultiplier changes
zoomChanged() zoom changes
diagStepChanged() diagStep changes
diffusionIterationsChanged() diffusionIterations changes
gridSpacingChanged() gridSpacing changes
lineLengthChanged() lineLength changes
lineBeginOffsetChanged() lineBeginOffset changes
noiseCh1ScaleChanged() noiseCh1Scale changes
noiseCh1StrengthChanged() noiseCh1Strength changes
noiseCh1SpeedChanged() noiseCh1Speed changes
noiseCh2ScaleChanged() noiseCh2Scale changes
noiseCh2StrengthChanged() noiseCh2Strength changes
noiseCh2SpeedChanged() noiseCh2Speed changes
noiseCh3ScaleChanged() noiseCh3Scale changes
noiseCh3StrengthChanged() noiseCh3Strength changes
noiseCh3SpeedChanged() noiseCh3Speed changes

Methods

Method Description
onFrameTick() Advance the simulation by one frame. Call this from a Timer every 16ms. Nothing happens without it.

Full Example

import FluxEngine 1.0
import QtQuick

FluxItem {
    id: fluid
    anchors.fill: parent
    running: true

    // Fluid
    viscosity: 8.0
    noiseMultiplier: 0.6
    timestep: 0.016667
    dissipation: 0.0
    pressureIterations: 19
    diffusionIterations: 3

    // Noise channels
    noiseCh1Scale: 2.8
    noiseCh1Strength: 1.0
    noiseCh1Speed: 0.001
    noiseCh2Scale: 15.0
    noiseCh2Strength: 0.7
    noiseCh2Speed: 0.006
    noiseCh3Scale: 30.0
    noiseCh3Strength: 0.5
    noiseCh3Speed: 0.012

    // Display
    debugMode: 5
    zoom: 1.6

    // Lines
    colorPreset: 1
    lineVariance: 0.55
    lineWidthMultiplier: 1.2
    gridSpacing: 15
    lineLength: 450.0
    lineBeginOffset: 0.4

    Timer {
        interval: 16
        running: parent.running
        repeat: true
        onTriggered: parent.onFrameTick()
    }
}