KSLCore/ksl.animation/AnimationCapture

AnimationCapture

class AnimationCapture(model: Model, output: JsonLinesAnimationOutput, mode: AnimationCapture.Mode = Mode.MEMORY, capturedReplications: Set<Int>? = setOf(1), captureSpec: CaptureSpec = CaptureSpec(), overlays: OverlaySpec = OverlaySpec.OFF, asyncCapacity: Int = AsyncAnimationSink.DEFAULT_CAPACITY, description: String? = null) : Closeable(source)

Captures an animation trace for a run of model and writes it to output (a .atf writer). This is the self-contained, renderer-agnostic capture mechanism of the animation core: it wires a sink onto the model, drives the sink's replication/experiment lifecycle, emits the experiment/replication marker events a renderer uses to delimit the trace, registers the automatic per-element emitters so the trace captures real activity, and cleans everything up on close.

It self-wires against a Model and depends only on the simulation core, so it is usable directly from the published KSLCore library — no application layer required. Construct it just before a run (its init installs the sink and observers) and close it after the run (releases the sink and closes the writer); the app-tier RunAttachmentIfc adapter does exactly this around a run's lifecycle.

Sink composition (outside-in): an optional ReplicationSelectingSink (to capture only chosen replications) wrapping an optional WindowedAnimationSink (a time window) wrapping the base sink chosen by mode — Mode.MEMORY (buffer a replication, flush the batch to the writer; best for post-processing replay) or Mode.ASYNC (stream events off the simulation thread via a writer thread; best for watching long runs).

Lifecycle (all on the simulation thread, via a ModelElementObserver on the model):

beforeExperiment emits AnimationEvent.ExperimentStarted
beforeReplication calls sink.onReplicationStart then emits AnimationEvent.ReplicationStarted
afterReplication emits AnimationEvent.ReplicationEnded then sink.onReplicationEnd (flush)
afterExperiment emits AnimationEvent.ExperimentEnded then sink.onExperimentEnd (drain/flush)

Parameters

model

the model to capture

output

the destination writer; its header is written on construction and it is closed by close

mode

the base sink strategy; defaults to Mode.MEMORY

capturedReplications

replication numbers to capture; null captures all. Defaults to replication 1 — the usual choice for an animation run.

captureSpec

selective-capture spec (elements to include/exclude, and an optional time window)

overlays

overlay-capture spec passed to the agent coordinators

asyncCapacity

bounded-queue capacity used in Mode.ASYNC

description

optional label written into the trace header (defaults to the model name)

Constructors

AnimationCapture

constructor(model: Model, output: JsonLinesAnimationOutput, mode: AnimationCapture.Mode = Mode.MEMORY, capturedReplications: Set<Int>? = setOf(1), captureSpec: CaptureSpec = CaptureSpec(), overlays: OverlaySpec = OverlaySpec.OFF, asyncCapacity: Int = AsyncAnimationSink.DEFAULT_CAPACITY, description: String? = null)

Types

Companion

object Companion

Mode

enum Mode : Enum<AnimationCapture.Mode>

The base-sink strategy.

Functions

open override fun close()

Runs every emitter undo action, detaches the lifecycle observer, restores the model's null sink, and closes the output writer. Idempotent: a second call is a no-op.