Package 

Class RiveCanvasSession

  • All Implemented Interfaces:
    java.lang.AutoCloseable 
    @RequiresApi(value = 29) 
public final class RiveCanvasSession
 implements AutoCloseable

    An entry point for Rive to render to a hardware accelerated Canvas using hardware bitmaps.

    ⚠️ This class must be closed when you no longer need it to free its resources. Call this only from the main thread.

    The session manages an advance and render loop after calling beginPlaying. While this render loop will produce bitmaps, it is the caller's responsibility to present them on a canvas using draw. Collect frameAvailable to know when new frames are available after rendering.

    Callers must pass touch events to the session with onTouchEvent to apply them to the state machine. Coordinates of the events are expected to be in the same space as the destination canvas of draw, and will be mapped into the render region.

    All instance methods are expected to be called on Android's main thread. Calling instance methods after close throws IllegalStateException (except repeated close, which remains idempotent).

    Call setRegion with the destination rectangle where frames should be presented. The render buffer dimensions are derived from this region's width and height.

    If viewModelInstance is supplied, this session binds it eagerly during initialization.

    This session is backed by a HardwareRenderBuffer. It owns that buffer's lifecycle and frame loop, but not the supplied Rive resources. These must be created and closed by the caller, and must outlive this session. The session will check that the supplied resources are from the same RiveWorker instance, but does not check that they are valid or properly initialized.

    The supplied riveWorker must be polled for messages. This is done separately from this session using RiveWorker.beginPolling, so that the caller can manage the worker lifecycle and share it across multiple sessions.

    • Constructor Detail

      • RiveCanvasSession

        RiveCanvasSession(CommandQueue riveWorker, Artboard artboard, StateMachine stateMachine, ViewModelInstance viewModelInstance, Fit fit, Integer clearColor)
        Parameters:
        riveWorker - The Rive worker that holds the resources to render.
        artboard - The artboard to render.
        stateMachine - The state machine to advance and render.
        viewModelInstance - An optional view model instance to bind to the state machine.
        fit - The Fit to use when rendering.
        clearColor - The color used to clear the draw region before drawing each frame.

    • Method Detail

      • getFrameAvailable

         final SharedFlow<Unit> getFrameAvailable()

        Emits whenever a newly published render frame becomes visible to this session.

        Hosts should collect this to invalidate their drawing target, then call draw.

      • setRegion

        @MainThread() final Unit setRegion(Rect region)

        Update the target draw region for rendering. This should be called at least once to initialize the session, and whenever the region changes.

        If the region's width or height changed, the underlying hardware render buffer is recreated. This is an expensive operation and should only be done when necessary.

        A region with width or height of 0 is treated as a "not renderable" state: the current render buffer is released and subsequent frames are skipped until a non-zero region is set.

        For Fit.Layout, size changes also update artboard sizing immediately. To observe the new sizing in rendered output, either beginPlaying must be actively running, or the caller must advance the supplied stateMachine manually (e.g. StateMachine.advance with 0 delta) before drawing.

        If only the region position changed, drawing and pointer mapping update without recreation.

      • beginPlaying

        @MainThread() final Unit beginPlaying(Lifecycle lifecycle, FrameTicker ticker)

        Runs the advance and render loop while lifecycle is RESUMED.

        The caller is expected to launch this from their own coroutine scope. It blocks the calling coroutine with a ticker loop, so it should typically be launched in a separate scope from the caller's main work.

        If the session is closed while this is running, the loop will exit, the function will return, and the session will stop advancing and rendering frames.

        Ensure setRegion has been called with a valid region before calling this. Without a valid region, the state machine will not be advanced and no frames will be rendered.

      • draw

        @MainThread() final Unit draw(Canvas canvas)

        Draws the latest rendered bitmap into the configured draw region of the canvas, if available.

        If no frame is available yet, only the draw-region clear color is painted.

        ⚠️ The supplied canvas must be hardware accelerated.

      • onTouchEvent

        @MainThread() final Boolean onTouchEvent(MotionEvent event)

        Forwards touch events to the state machine pointer APIs.

        Coordinates are interpreted in the same canvas space as draw, then mapped into the configured draw region set with setRegion before forwarding to Rive.