Crate lactea 

MilkDrop engine: preset + expressions + audio + shaders driving lactea-render. Embeddable into any wgpu host: bytes in (presets, textures, PCM), a host-provided wgpu::Device / Queue and target view out. No windows, no audio devices, no filesystem.

This crate is the CPU side of MilkDrop 2’s RenderFrame (milkdropfs.cpp + state.cpp), behaving like projectM where projectM and MilkDrop 2 differ (projectM is the reference; docs/divergences.md, docs/engine.md).

use lactea::{Engine, EngineConfig, FrameClock, Transition};
let mut engine = Engine::new(device, queue, EngineConfig::default()).unwrap();
let report = engine.load_preset(milk, "my preset", Transition::Cut).unwrap();
for frame in 0..60u32 {
    engine.push_pcm_f32(pcm, 2);
    let mut enc = device.create_command_encoder(&Default::default());
    engine.render(&mut enc, target, FrameClock { time: frame as f64 / 60.0, frame });
    queue.submit(Some(enc.finish()));
}

Preset changes: Transition::Cut replaces the preset at once, Transition::Soft blends the old and the new preset over a number of seconds (both keep running: projectM’s shader transitions by default, MilkDrop 2’s per-vertex blend with Compat::MilkDrop2); see docs/engine.md.

Modules

auto_cut

MilkDrop 3 AutoHardCutMode 0..7 (MD3 3.37, docs/md3.md “Auto hard cuts”): beat-driven preset changes and composite-shader effect injection.

Structs

AnimFrame

One frame of an animated image.

AnimatedImage

An animated image (a GIF): every frame is a full canvas.

AudioFrame

Everything the renderer needs for one frame.

CtrlKeys

The arrow keys held together with Ctrl (ctrllt ctrlrt ctrldn ctrlup): BeatDrop sets them from Ctrl + arrow key events. The host reports the current state; the engine samples it once per rendered frame.

DateTime

The wall clock BeatDrop reads with GetLocalTime. The engine never looks at the system clock (a library must be deterministic); until the host calls crate::Engine::set_date_time it derives the time of day from the frame clock instead (see crate::Engine::set_date_time).

DebugImage

A rendered stage read back from the GPU: RGBA8, row 0 = top.

DoublePresetInfo

What the host can show about the double preset on screen (crate::Engine::double_preset_info).

Engine

The MilkDrop engine. See the crate docs.

EngineConfig

Engine construction parameters.

Filter

The playlist’s include/exclude list (projectm_playlist_set_filter).

ForcedFrame

Oracle state to impose on the next rendered frame (crate::Engine::force_next_frame).

FrameClock

Time of the frame about to be rendered.

Hook

An optional callback taking &A. Clones share the same underlying callback.

Image

A decoded texture: RGBA8, row 0 = top.

LoadRequest

What the host’s loader is asked to do (projectm_playlist_preset_load_event).

Md3Locks

The user locks of the random block (forcePattern, forceProgress, dirLock), all off by default.

Md3PatternInstance

Everything a generator needs: the values of the .milk2 header keys.

MediaFiles

Index of the media files a host can read, with the lookups of MilkDrop 3.

MouseState

The host’s mouse, as MD3’s _c14 shader constant (mouse, mouse_x .. of the shader prelude) sees it. Preset expressions cannot read it: MD3’s expression grammar has no dotted identifiers, so mouse.x does not compile there.

Playlist

An ordered preset list with projectM’s navigation rules. See the module docs.

PresetControl

projectM’s timing + switch-request state. Deterministic: the easter-egg duration sampling is seeded from the run seed.

PresetReport

What Engine::load_preset found.

Renderer

The MilkDrop 2 frame renderer. See the crate docs for the pass order.

ShaderFallback

A shader that was replaced by a default one.

ShaderOverride

User-supplied HLSL for a locked MilkDrop 3 preset (see EngineConfig::shader_overrides).

SwitchFailure

A failed preset load (projectm_preset_switch_failed_event): the preset’s name and the error text. The previously loaded preset keeps running.

SwitchRequest

The host should load another preset (projectm_preset_switch_requested_event).

TransitionInfo

The soft cut in progress (Engine::transition_info).

Enums

Compat

Which reference behaviour the renderer follows where MilkDrop 2 (third_party/md2) and projectM differ. Default: projectM.

DoubleMode

Where a double preset is in its life (DoublePresetInfo::mode).

EngineError

Errors from Engine::load_preset.

Md3Pattern

The 30 MD3 blend patterns, in MD3’s order (index() is the discriminant).

Media

What a TextureProvider found for an MD3 resource.

PassKind

Which pass a translated shader runs in.

ShaderOutcome

How a warp / composite shader slot ended up.

SortOrder

Sort direction for Playlist::sort.

SortPredicate

What Playlist::sort compares.

Stage

Which intermediate or final image a dump frame holds.

TouchType

projectm_touch_type (types.h:68-79): the waveform a touch asks for.

Transition

How Engine::load_preset replaces the current preset.

TransitionKind

The six built-in transition shaders, in projectM’s TransitionShaderManager order.

Constants

DEFAULT_RETRY_COUNT

Default number of failed loads in a row before the failure event is raised.

HARD_CUT_MIN_FRAMES

A hard cut needs more than this many rendered frames first (m_frameCount > 50).

IDLE_PRESET

.milk source of the idle preset.

IDLE_PRESET_NAME

Display name the idle preset is loaded under (Engine::preset_name).

INSERT_AT_END

Pass as index to insert at the end (Playlist::InsertAtEnd).

MAX_HISTORY

Maximum entries of the playback history (Playlist::MaxHistoryItems).

TEXTURE_EXTENSIONS

Extensions MD3 looks for when a shader names a texture, in its order (.jpeg is accepted right after .jpg).

VCS_VERSION

git describe --always --dirty of the source this crate was built from; "unknown" for a build outside a git checkout of it (a published crate). projectM’s projectm_get_vcs_version_string.

Traits

TextureProvider

Source of user textures (sampler_<name> in preset shaders).

Functions

compat_for_preset

The compatibility mode EngineConfig::auto_compat picks for a preset file: Compat::MilkDrop3 when lactea_preset::detect_compat finds evidence of a MilkDrop 3 feature, otherwise Compat::ProjectM (MilkDrop 2 files are indistinguishable from projectM ones, so this never returns it; Engine::load_preset reaches it only by retrying a preset projectM rejects with a compile error). Pure on the bytes; the evidence itself is lactea_preset::detect_compat.

decode_gif

Decode a GIF into full-canvas frames.

default_enabled_patterns

The 13 patterns random soft cuts may pick when settings.ini has no [transitions] section.

md3_draw_progress

The progress of a double preset drawn for pattern: round((rand() / 32767 * A + B) * 100) / 100.

md3_fill_vertinfo

Fill the (gx + 1) * (gy + 1) mesh vi (vi[y * (gx + 1) + x] = (a, c)) with the pattern. aspect is (m_fAspectX, m_fAspectY). Pure: the same instance gives the same mesh, nothing is read from vi.

md3_random_instance

The random block of RandomizeBlendPattern, once per preset change: draws, in this order, the pattern (a uniform element of enabled, {zoom} if empty), the direction (+-1, unless locked), r1..r5 and, in double-preset mode, the pattern again if auto_hardcut (one of the first six patterns, ignoring enabled) and the progress. Ordinary soft cuts have progress = 1.

Type Aliases

FailedFn

Callback of Playlist::set_preset_switch_failed_callback: (filename, message).

SwitchedFn

Callback of Playlist::set_preset_switched_callback: (is_hard_cut, index).