sdk/fidl/fuchsia.ui.sketchy/commands.fidl

// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.ui.sketchy;

using fuchsia.ui.gfx;

union Command {
    // Resource creation and lifecycle.
    CreateResourceCmd create_resource;
    ReleaseResourceCmd release_resource;

    // Stroke commands.
    ClearStrokeCmd clear_stroke;
    BeginStrokeCmd begin_stroke;
    ExtendStrokeCmd extend_stroke;
    FinishStrokeCmd finish_stroke;
    SetStrokeStyleCmd set_style;
    SetStrokePathCmd set_path;

    // StrokeGroup commands.
    AddStrokeCmd add_stroke;
    RemoveStrokeCmd remove_stroke;
    ClearGroupCmd clear_group;

    // Pen commands.
    SetPenStyleCmd set_pen_style;

    // Interaction with Scenic scene-graph:

    // Import the specified Scenic resource.  Currently only the following
    // resource types are supported:
    // - NODE: imported nodes enable the use of ui.fuchsia.ui.gfx.AddChildCmd to insert
    //         stroke-groups into a Scenic scene-graph.
    // - MATERIAL: imported materials can be applied to a stroke-style.
    fuchsia.ui.gfx.ImportResourceCmd scenic_import_resource;

    // Attach a stroke-group as a child of the specified imported Scenic node.
    fuchsia.ui.gfx.AddChildCmd scenic_add_child;

    // Detach a stroke-group from the Scenic node that it is attached to, if any.
    fuchsia.ui.gfx.DetachCmd scenic_detach;

    // Set the material of a stroke-style.  This material will be applied to any
    // strokes/stroke-groups that use this style.
    fuchsia.ui.gfx.SetMaterialCmd scenic_set_material;
};

// Instantiates a new resource.
struct CreateResourceCmd {
    // The ID of the resource to create; this ID must not currently be used within
    // the session.  The client may use this ID to refer to the resource in
    // subsequent commands.
    uint32 id;
    // Specifies the type of resource to construct, as well as any other required
    // data.
    ResourceArgs args;
};

// Releases the client's reference to the resource; it is then illegal to use
// the ID in subsequent Commands.  Other references to the resource may exist, so
// releasing the resource does not result in its immediate destruction; it is
// only destroyed once the last reference is released.  For example, after a
// stroke is added to a stroke-group, the group will keep the it alive even
// after the client releases the stroke.
//

// TODO: edge cases.  What about releasing a stroke that is currently being
// drawn by Begin/Extend/FinishStrokeCmd?
struct ReleaseResourceCmd {
    // The ID of the resource to be dereferenced.  The ID must currently reference
    // a resource (i.e. it must match one from a previous CreateResourceCmd, and
    // must not have match one from a subsequent ReleaseResourceCmd).
    uint32 id;
};

// Clear the path of the specified stroke.  Must not be called in the middle of
// Begin/Extend/FinishStroke.
struct ClearStrokeCmd {
    uint32 stroke_id;
};

// Start drawing a stroke with a pen.
struct BeginStrokeCmd {
    // ID of the stroke to draw with the pen.  This must be a new stroke, or one
    // which has been cleared via ClearStrokeCmd.
    uint32 stroke_id;
    // ID of the pen to draw the stroke with.
    uint32 pen_id;
    // Describes the time, position, etc. that the stroke was started.
    Touch touch;
};

// Continue drawing a stroke with a pen.  The stroke must have previously been
// started (via BeginStrokeCmd), but not finished.
struct ExtendStrokeCmd {
    // ID of the stroke that is being drawn.
    uint32 stroke_id;
    // ID of the pen that is drawing the stroke.  Must match the ID provided
    // to BeginStrokeCmd.
    uint32 pen_id;
    // Touch events that describe the trajectory of the stroke since the previous
    // BeginStrokeCmd or ExtendStrokeCmd.
    vector<Touch> touches;
    // Procedurally-generated touch events that describe the predicted future
    // trajectory of the stroke.  Sketchy uses these to improve perceived latency
    // while the stroke is being drawn, but they have no impact on the finished
    // stroke.
    // TODO: this may change to reflect however Scenic exposes predicted events.
    vector<Touch> predicted_touches;
};

// Finish drawing a stroke with a pen.
struct FinishStrokeCmd {
    // ID of the stroke that is being drawn.
    uint32 stroke_id;
    // ID of the pen that is drawing the stroke.  Must match the ID provided
    // to BeginStrokeCmd.
    uint32 pen_id;
};

// Set the style of the specified stroke.
struct SetStrokeStyleCmd {
    uint32 stroke_id;
    uint32 style_id;
};

// Set the path of a stroke.  This cannot be applied to a stroke that is in the
// middle of Begin/Extend/FinishStroke.
struct SetStrokePathCmd {
    // ID of the stroke whose path is to be set.
    uint32 stroke_id;
    // Describes the stroke's new path.
    StrokePath path;
};

// Add a stroke to a stroke-group.  The stroke must not currently be a member of
// any group, including the specified group.
struct AddStrokeCmd {
    uint32 group_id;
    uint32 stroke_id;
};

// Remove a stroke from a stroke-group.  The stroke must currently be a member
// of that group.
struct RemoveStrokeCmd {
    uint32 group_id;
    uint32 stroke_id;
};

// Remove all strokes from the specified stroke-group.  These strokes may be
// re-added later to the same group, or a different one.
struct ClearGroupCmd {
    uint32 group_id;
};

// Set the style that is applied to strokes that are subsequently drawn by the
// specified pen.
struct SetPenStyleCmd {
    uint32 pen_id;
    uint32 style_id;
};