1// Copyright 2024-2025 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//      http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15// Proto definitions for delta-coded storage of Ink strokes.
16
17syntax = "proto2";
18
19package androidx.ink.storage.proto;
20
21import "coded_numeric_run.proto";
22
23// A struct-of-arrays representing a complete StrokeInputBatch, compressed
24// lossily using delta coding. Each numeric run, if present, must have the same
25// number of elements (one for each input point).
26//
27// A StrokeInputBatch and a brush specification together can be used to
28// generate a stroke mesh, which can then be rendered to the screen. Once a
29// StrokeInputBatch is recorded, it is generally never changed; however, a
30// client app can change the brush specification after the fact, allowing a new
31// stroke mesh to be generated from the original StrokeInputBatch.
32message CodedStrokeInputBatch {
33  // The original (pre-stroke-modeler) sequence of input positions for the
34  // stroke, in stroke space.  Clients are generally free to define some of the
35  // stroke space however they want (e.g. whatever units they want), although in
36  // order for stroke modeling and prediction to make sense, it's generally
37  // expected that stroke stroke for an in-progress stroke maps to physical
38  // space in a straightforward way (isotropic and conformal, i.e. without any
39  // nonuniform scaling or angle deformation).
40  optional CodedNumericRun x_stroke_space = 1;
41  optional CodedNumericRun y_stroke_space = 2;
42
43  // Time elapsed for each input point, measured in seconds from the start of
44  // the stroke.
45  optional CodedNumericRun elapsed_time_seconds = 3;
46
47  // The stylus/touch pressure for each input point, from zero (inclusive) to 1
48  // (inclusive).
49  //
50  // This field can be omitted for clients that will never use any
51  // pressure-sensitive brush tips, or for input streams from sources that don't
52  // report pressure (e.g. mouse).
53  optional CodedNumericRun pressure = 4;
54
55  // The stylus tilt for each input point, from zero (inclusive) to pi/2
56  // (inclusive). A value of zero means that the stylus is perpendicular to the
57  // drawing surface, while a value of pi/2 would mean that the stylus was flat
58  // against the drawing surface.
59  //
60  // This field can be omitted for clients that will never use any
61  // tilt-sensitive brush tips, or for input streams from sources that don't
62  // report tilt (e.g. mouse or touch).
63  optional CodedNumericRun tilt = 5;
64
65  // The stylus orientation for each input point, from zero (inclusive) to 2*pi
66  // (exclusive). A value of zero means that the ray from the tip of the stylus
67  // towards the other end of the stylus points along the positive x-axis, and
68  // the orientation angle increases as the stylus moves from the positive
69  // x-axis towards the positive y-axis (i.e. counter-clockwise if positive-y is
70  // up, or clockwise if positive-y is down).
71  //
72  // This field can be omitted for clients that will never use any
73  // orientation-sensitive brush tips, or for input streams from sources that
74  // don't report orientation (e.g. mouse or touch).
75  optional CodedNumericRun orientation = 6;
76
77  // The `ToolType` for the entire `Stroke` -- the same value holds for all the
78  // individual input points. Maps to `InputToolType` values.
79  enum ToolType {
80    UNKNOWN_TYPE = 0;
81    MOUSE = 1;
82    TOUCH = 2;
83    STYLUS = 3;
84  }
85  optional ToolType tool_type = 7;
86
87  // The physical distance that the pointer traveled for each unit of distance
88  // in stroke space. For stylus/touch, this is the real-world distance that the
89  // stylus/fingertip moved in physical space; for mouse, this is the visual
90  // distance that the mouse pointer traveled along the surface of the display.
91  //
92  // A missing or zero value indicates that the relationship between stroke
93  // space and physical space is unknown or ill-defined for this input batch.
94  optional float stroke_unit_length_in_centimeters = 8;
95
96  // The seed value that should be used for seeding any noise generators for
97  // brush behaviors when a full stroke is regenerated with this input batch.
98  optional fixed32 noise_seed = 9;
99}
100