Package 

Class CommandQueue

  • 
public final class CommandQueue

    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.

    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 rememberCommandQueue composable.

    • Constructor Detail

      • CommandQueue

        CommandQueue(CoroutineScope scope)

    • Method Detail

      • loadFile

         final FileHandle loadFile(ByteArray bytes)

        Load a Rive into the command queue. Returns the handle in either onFileLoaded or an error in onFileError.

        Parameters:
        bytes - The bytes of the Rive file to load.

      • deleteFile

         final Unit deleteFile(FileHandle fileHandle)

        Counterpart to loadFile to free the resources associated to the file handle.

        Parameters:
        fileHandle - The handle of the file to delete.

      • getArtboardNames

         final List<String> getArtboardNames(FileHandle fileHandle)

        Query the file for available artboard names. Returns on onArtboardsListed.

        Parameters:
        fileHandle - The handle of the file to query.

      • getStateMachineNames

         final List<String> getStateMachineNames(ArtboardHandle artboardHandle)

        Query the artboard for available state machine names. Returns on onStateMachinesListed.

        Parameters:
        artboardHandle - The handle of the artboard to query.

      • getViewModelNames

         final List<String> getViewModelNames(FileHandle fileHandle)

        Query the file for available view model names. Returns on onViewModelsListed.

        Parameters:
        fileHandle - The handle of the file to query.

      • getViewModelInstanceNames

         final List<String> getViewModelInstanceNames(FileHandle fileHandle, String viewModelName)

        Query the file for available view model instance names for the given view model. Returns on onViewModelInstancesListed.

        Parameters:
        fileHandle - The handle of the file that owns the view model.
        viewModelName - The name of the view model to query.

      • getViewModelProperties

         final List<ViewModel.Property> getViewModelProperties(FileHandle fileHandle, String viewModelName)

        Query the file for available view model properties for the given view model. Returns on onViewModelPropertiesListed.

        Parameters:
        fileHandle - The handle of the file that owns the view model.
        viewModelName - The name of the view model to query.

      • getEnums

         final List<File.Enum> getEnums(FileHandle fileHandle)

        Query the file for available enums. Returns on onEnumsListed.

        Parameters:
        fileHandle - The handle of the file to query.

      • createDefaultArtboard

         final ArtboardHandle createDefaultArtboard(FileHandle fileHandle)

        Create the default artboard for the given file. This is the artboard marked "Default" in the Rive editor.

        Parameters:
        fileHandle - The handle of the file that owns the artboard.

      • createArtboardByName

         final ArtboardHandle createArtboardByName(FileHandle fileHandle, String name)

        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.

        Parameters:
        fileHandle - The handle of the file that owns the artboard.
        name - The name of the artboard to create.

      • createDefaultStateMachine

         final StateMachineHandle createDefaultStateMachine(ArtboardHandle artboardHandle)

        Create the default state machine for the given artboard. This is the state machine marked "Default" in the Rive editor.

        Parameters:
        artboardHandle - The handle of the artboard that owns the state machine.

      • createStateMachineByName

         final StateMachineHandle createStateMachineByName(ArtboardHandle artboardHandle, String name)

        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.

        Parameters:
        artboardHandle - The handle of the artboard that owns the state machine.
        name - The name of the state machine to create.

      • advanceStateMachine

         final Unit advanceStateMachine(StateMachineHandle stateMachineHandle, Long deltaTimeNs)

        Advance the state machine by the given delta time in nanoseconds.

        Parameters:
        stateMachineHandle - The handle of the state machine to advance.
        deltaTimeNs - The delta time in nanoseconds to advance the state machine by.

      • createViewModelInstance

         final ViewModelInstanceHandle createViewModelInstance(FileHandle fileHandle, ViewModelInstanceSource source)

        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).

        Parameters:
        fileHandle - The handle of the file that owns the view model instance.
        source - The source of the view model instance to create, which internally also has a view model source.

      • deleteViewModelInstance

         final Unit deleteViewModelInstance(ViewModelInstanceHandle viewModelInstanceHandle)

        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.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance to delete.

      • bindViewModelInstance

         final Unit bindViewModelInstance(StateMachineHandle stateMachineHandle, ViewModelInstanceHandle viewModelInstanceHandle)

        Bind a view model instance to a state machine. This establishes the data binding for the instance's properties.

        Parameters:
        stateMachineHandle - The handle of the state machine to bind to.
        viewModelInstanceHandle - The handle of the view model instance to bind.

      • setNumberProperty

         final Unit setNumberProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath, Float value)

        Update a number property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be updated.
        value - The new value of the property.

      • getNumberProperty

         final Float getNumberProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath)

        Get a number property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be retrieved.

      • setStringProperty

         final Unit setStringProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath, String value)

        Set a string property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be updated.
        value - The new value of the property.

      • getStringProperty

         final String getStringProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath)

        Get a string property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be retrieved.

      • setBooleanProperty

         final Unit setBooleanProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath, Boolean value)

        Set a boolean property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be updated.
        value - The new value of the property.

      • getBooleanProperty

         final Boolean getBooleanProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath)

        Get a boolean property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be retrieved.

      • setEnumProperty

         final Unit setEnumProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath, String value)

        Set an enum property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be updated.
        value - The new value of the property, as a string.

      • getEnumProperty

         final String getEnumProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath)

        Get an enum property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be retrieved.

      • setColorProperty

         final Unit setColorProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath, @ColorInt() Integer value)

        Set a color property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be updated.
        value - The new value of the property, as an AARRGGBB ColorInt.

      • getColorProperty

         final Integer getColorProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath)

        Get a color property's value on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be retrieved.

      • fireTriggerProperty

         final Unit fireTriggerProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath)

        Fire a trigger property on the view model instance.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be fired.

      • subscribeToProperty

         final Unit subscribeToProperty(ViewModelInstanceHandle viewModelInstanceHandle, String propertyPath, ViewModel.PropertyDataType propertyType)

        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.

        Parameters:
        viewModelInstanceHandle - The handle of the view model instance that the property belongs to.
        propertyPath - The path to the property that should be subscribed to.
        propertyType - The type of the property to subscribe to.

      • decodeImage

         final ImageHandle decodeImage(ByteArray bytes)

        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.

        Images may be used to supply a referenced asset in a Rive file with registerImage or used for data binding (forthcoming).

        Parameters:
        bytes - The bytes of the image file to decode.

      • deleteImage

         final Unit deleteImage(ImageHandle imageHandle)

        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.

        Parameters:
        imageHandle - The handle of the image to delete.

      • registerImage

         final Unit registerImage(String name, ImageHandle imageHandle)

        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.

        The CommandServer will keep a reference to the image. For it to be fully released, you must unregister it with unregisterImage.

        Registrations are global to the CommandQueue, meaning that the name will be used to fulfill any file loaded by this CommandQueue that references the asset with the same name.

        The same image can be registered multiple times with different names, allowing it to fulfill multiple referenced assets in all Rive files on this CommandQueue.

        Parameters:
        name - The name of the referenced asset to fulfill.
        imageHandle - The handle of the image to register.

      • unregisterImage

         final Unit unregisterImage(String name)

        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.

        Parameters:
        name - The name of the referenced asset to unregister, the same used in registerImage.

      • decodeAudio

         final AudioHandle decodeAudio(ByteArray bytes)

        Decode an audio file from the given bytes. The decoded audio is stored on the CommandServer.

        Audio may be used to supply a referenced asset in a Rive file with registerAudio.

        Parameters:
        bytes - The bytes of the audio file to decode.

      • deleteAudio

         final Unit deleteAudio(AudioHandle audioHandle)

        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.

        Parameters:
        audioHandle - The handle of the audio to delete.

      • registerAudio

         final Unit registerAudio(String name, AudioHandle audioHandle)

        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.

        The CommandServer will keep a reference to the audio. For it to be fully released, you must unregister it with unregisterAudio.

        Registrations are global to the CommandQueue, meaning that the name will be used to fulfill any file loaded by this CommandQueue that references the asset with the same name.

        The same audio can be registered multiple times with different names, allowing it to fulfill multiple referenced assets in all Rive files on this CommandQueue.

        Parameters:
        name - The name of the referenced asset to fulfill.
        audioHandle - The handle of the audio to register.

      • unregisterAudio

         final Unit unregisterAudio(String name)

        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.

        Parameters:
        name - The name of the referenced asset to unregister, the same used in registerAudio.

      • decodeFont

         final FontHandle decodeFont(ByteArray bytes)

        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.

        Fonts may be used to supply a referenced asset in a Rive file with registerFont.

        Parameters:
        bytes - The bytes of the font file to decode.

      • deleteFont

         final Unit deleteFont(FontHandle fontHandle)

        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.

        Parameters:
        fontHandle - The handle of the font to delete.

      • registerFont

         final Unit registerFont(String name, FontHandle fontHandle)

        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.

        The CommandServer will keep a reference to the font. For it to be fully released, you must unregister it with unregisterFont.

        Registrations are global to the CommandQueue, meaning that the name will be used to fulfill any file loaded by this CommandQueue that references the asset with the same name.

        The same font can be registered multiple times with different names, allowing it to fulfill multiple referenced assets in all Rive files on this CommandQueue.

        Parameters:
        name - The name of the referenced asset to fulfill.
        fontHandle - The handle of the font to register.

      • unregisterFont

         final Unit unregisterFont(String name)

        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.

        Parameters:
        name - The name of the referenced asset to unregister, the same used in registerFont.

      • pointerMove

         final Unit pointerMove(StateMachineHandle stateMachineHandle, Fit fit, Alignment alignment, Float surfaceWidth, Float surfaceHeight, Integer pointerID, Float pointerX, Float pointerY)

        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.

        The additional parameters are required for calculating the pointer position in artboard space.

        Parameters:
        stateMachineHandle - The handle of the state machine to notify.
        fit - The fit mode of the artboard.
        alignment - The alignment of the artboard.
        surfaceWidth - The width of the surface the artboard is drawn to.
        surfaceHeight - The height of the surface the artboard is drawn to.
        pointerX - The X coordinate of the pointer in surface space.
        pointerY - The Y coordinate of the pointer in surface space.

      • pointerDown

         final Unit pointerDown(StateMachineHandle stateMachineHandle, Fit fit, Alignment alignment, Float surfaceWidth, Float surfaceHeight, Integer pointerID, Float pointerX, Float pointerY)

        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.

        The additional parameters are required for calculating the pointer position in artboard space.

        Parameters:
        stateMachineHandle - The handle of the state machine to notify.
        fit - The fit mode of the artboard.
        alignment - The alignment of the artboard.
        surfaceWidth - The width of the surface the artboard is drawn to.
        surfaceHeight - The height of the surface the artboard is drawn to.
        pointerX - The X coordinate of the pointer in surface space.
        pointerY - The Y coordinate of the pointer in surface space.

      • pointerUp

         final Unit pointerUp(StateMachineHandle stateMachineHandle, Fit fit, Alignment alignment, Float surfaceWidth, Float surfaceHeight, Integer pointerID, Float pointerX, Float pointerY)

        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.

        The additional parameters are required for calculating the pointer position in artboard space.

        Parameters:
        stateMachineHandle - The handle of the state machine to notify.
        fit - The fit mode of the artboard.
        alignment - The alignment of the artboard.
        surfaceWidth - The width of the surface the artboard is drawn to.
        surfaceHeight - The height of the surface the artboard is drawn to.
        pointerX - The X coordinate of the pointer in surface space.
        pointerY - The Y coordinate of the pointer in surface space.

      • pointerExit

         final Unit pointerExit(StateMachineHandle stateMachineHandle, Fit fit, Alignment alignment, Float surfaceWidth, Float surfaceHeight, Integer pointerID, Float pointerX, Float pointerY)

        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.

        The additional parameters are required for calculating the pointer position in artboard space.

        Parameters:
        stateMachineHandle - The handle of the state machine to notify.
        fit - The fit mode of the artboard.
        alignment - The alignment of the artboard.
        surfaceWidth - The width of the surface the artboard is drawn to.
        surfaceHeight - The height of the surface the artboard is drawn to.
        pointerX - The X coordinate of the pointer in surface space.
        pointerY - The Y coordinate of the pointer in surface space.

      • pollMessages

         final Unit pollMessages()

        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.

      • draw

         final Unit draw(ArtboardHandle artboardHandle, StateMachineHandle stateMachineHandle, Fit fit, Alignment alignment, RiveSurface surface, Integer clearColor)

        Draw the artboard with the given state machine.

        Parameters:
        artboardHandle - The handle of the artboard to draw.
        stateMachineHandle - The handle of the state machine to use for drawing.
        fit - The fit mode of the artboard.
        alignment - The alignment of the artboard.
        surface - The surface to draw to.
        clearColor - The color to clear the surface with before drawing, in AARRGGBB format.