Command
A CommandQueue is the worker that runs Rive in a thread. It holds all of the state, including assets (images, audio, and fonts), Rive files, artboards, state machines, and view model instances.
Instances of the command queue are reference counted. At initialization, the command queue has a ref count of 1. Call acquire to increment the ref count, and release to decrement it. When the ref count reaches 0, the command queue is disposed, and its resources are released. Using a disposed command queue will throw an IllegalStateException. Any pending operations will be notified with a CancellationException.
Rive resources such as manually-created files, assets, and surfaces may acquire references to the command queue. Releasing the command queue's own reference is not enough to fully dispose the worker while those resources remain open; close each resource when you no longer need it.
The command queue normally is passed into rememberRiveFile or, alternatively, created by default if one is not supplied. This is then transitively supplied to other Rive elements, such as artboards, when the Rive file is passed in.
It is important to understand the threading model. Each command queue begins a system thread. The "command" part of the name indicates that "commands" are serialized to the CommandServer, all in the Rive C++ runtime. This design minimizes shared state. As a consequence, all operations are asynchronous.
If the operation creates a resource, it will be received as a handle, a monotonically increasing opaque identifier that can be translated to a pointer on the command server. A handle can be used immediately, since commands are ordered, ensuring validity at the time of any operation that uses it.
If instead the operation is a query, such as getting the names of artboards or view models, it is represented as a suspend function. In most cases, the result can be cached, as Rive files are largely immutable.
You may choose to have multiple command queues to run multiple Rive files in parallel. However, be aware that these instances cannot share memory. This means that each file and asset must be loaded into each command queue separately.
A command queue needs to be polled to receive messages from the command server. This is handled by the rememberRiveWorker composable or by calling beginPolling.
Parameters
Render context owned by this command queue after native startup succeeds.
Native bridge used to create and communicate with the command queue. This is injectable so unit tests can mock JNI calls without loading native code.
Whether native draw/advance tracing should start enabled.
Allocated native command queue created by createNativeCommandQueueResources. Supplying it lets backend fallback finish native startup before ownership is transferred to this instance.
Types
Contains the data associated with a property update event.
Properties
Hot flow that emits when any boolean property is updated.
Hot flow that emits when any color property is updated.
Hot flow that emits when any enum property is updated.
Whether this object has been disposed due to the reference count reaching 0.
Hot flow that emits when any number property is updated.
Flow that emits when a state machine has settled.
Hot flow that emits when any string property is updated.
Hot flow that emits when any trigger property is fired.
Functions
Advance the state machine by the given delta time in nanoseconds.
Appends a view model instance to the end of a list property.
Begin polling the CommandQueue for messages from the CommandServer. Without this, callbacks and errors will not be delivered. This should typically be called by tying to the lifecycle scope of the containing activity, fragment, or composable, e.g. with lifecycleScope.launch.
Bind a view model instance to a state machine. This establishes the data binding for the instance's properties.
Create an artboard by name for the given file. This is useful when the file has multiple artboards and you want to create a specific one.
Create the default artboard for the given file. This is the artboard marked "Default" in the Rive editor.
Create the default state machine for the given artboard. This is the state machine marked "Default" in the Rive editor.
Create an off-screen image surface for rendering to a buffer.
Create a Rive rendering surface for Rive to draw into.
Create a state machine by name for the given artboard. This is useful when the artboard has multiple state machines and you want to create a specific one.
Create a new view model instance based on the given source. The source is a combination of a view model source and an instance source, which multiply to capture all the possible ways to create an instance (+1 for referencing).
Decode an audio file from the given bytes. The decoded audio is stored on the CommandServer.
Decode a font file from the given bytes. The bytes are for a font file, such as TTF. The decoded font is stored on the CommandServer.
Decode an image file from the given bytes. The bytes are for a compressed image format such as PNG or JPEG. The decoded image is stored on the CommandServer.
Delete an artboard and free its resources. This is useful when you no longer need the artboard and want to free up memory. Counterpart to createDefaultArtboard or createArtboardByName.
Delete audio and free its resources. This is useful when you no longer need the audio and want to free up memory. Counterpart to decodeAudio.
Counterpart to loadFile to free the resources associated to the file handle.
Delete a font and free its resources. This is useful when you no longer need the font and want to free up memory. Counterpart to decodeFont.
Delete an image and free its resources. This is useful when you no longer need the image and want to free up memory. Counterpart to decodeImage.
Delete a state machine and free its resources. This is useful when you no longer need the state machine and want to free up memory. Counterpart to createDefaultStateMachine or createStateMachineByName.
Delete a view model instance and free its resources. This is useful when you no longer need the view model instance and want to free up memory. Counterpart to createViewModelInstance.
Destroy a Rive rendering surface. The surface will not be valid for use after this call.
Draw the artboard with the given state machine.
Renders the current state of an artboard/state machine pair into an off-screen buffer that can be used for snapshot comparisons.
Fire a trigger property on the view model instance.
Query the file for available artboard names. Returns on onArtboardsListed.
Get a boolean property's value on the view model instance.
Get a color property's value on the view model instance.
Query the default view model info for an artboard. Returns on onDefaultViewModelInfoReceived.
Get an enum property's value on the view model instance.
Query the file for available enums. Returns on onEnumsListed.
Gets the size of a list property on the view model instance.
Get a number property's value on the view model instance.
Query the artboard for available state machine names. Returns on onStateMachinesListed.
Get a string property's value on the view model instance.
Query the file for available view model instance names for the given view model. Returns on onViewModelInstancesListed.
Query the file for available view model names. Returns on onViewModelsListed.
Query the file for available view model properties for the given view model. Returns on onViewModelPropertiesListed.
Inserts a view model instance into a list property at the specified index.
Load a Rive into the command queue. Returns the handle in either onFileLoaded or an error in onFileError.
Notify the state machine that the pointer (typically a user's touch) has touched down. This is used to interact with the state machine, triggering pointer events.
Notify the state machine that the pointer (typically a user's touch) has exited the surface. This is used to interact with the state machine, triggering pointer events.
Notify the state machine that the pointer (typically a user's touch) has moved. This is used to interact with the state machine, triggering pointer events.
Notify the state machine that the pointer (typically a user's touch) has lifted up. This is used to interact with the state machine, triggering pointer events.
Poll messages from the CommandServer to the CommandQueue. This is the channel that all callbacks and errors arrive on. Should be called every frame, regardless of whether there is any advancing or drawing.
Register audio as an asset with the given name. This allows the audio to be used to fulfill a referenced asset when loading a Rive file.
Register a font as an asset with the given name. This allows the font to be used to fulfill a referenced asset when loading a Rive file.
Register an image as an asset with the given name. This allows the image to be used to fulfill a referenced asset when loading a Rive file.
Removes a view model instance from a list property.
Removes an item from a list property at the specified index.
Resets an artboard to its original dimensions.
Resizes an artboard to match the dimensions of the given surface.
Assign an artboard to a bindable artboard property on the view model instance, or clear the property if artboardHandle is null.
Set a boolean property's value on the view model instance.
Set a color property's value on the view model instance.
Set an enum property's value on the view model instance.
Assign an image to an image property on the view model instance.
Update a number property's value on the view model instance.
Set a string property's value on the view model instance.
Enables or disables native command server tracing for draw and advance work.
Assign a view model instance to a nested view model property on the view model instance.
Subscribe to changes to a property on the view model instance. Updates will be emitted on the flow of the corresponding type, e.g. numberPropertyFlow for number properties.
Swaps two items in a list property by their indices.
Unregister audio that was previously registered with registerAudio. This will remove the reference to the audio from the CommandServer, allowing the memory to be freed if the audio handle was also deleted with deleteAudio.
Unregister a font that was previously registered with registerFont. This will remove the reference to the font from the CommandServer, allowing the memory to be freed if the font handle was also deleted with deleteFont.
Unregister an image that was previously registered with registerImage. This will remove the reference to the image from the CommandServer, allowing the memory to be freed if the image handle was also deleted with deleteImage.
Tie this CommandQueue's lifetime to a LifecycleOwner. This will call release when the owner's lifecycle reaches DESTROYED. Returns an AutoCloseable that can be used to manually release early; calling it is idempotent.