sdk/fidl/fuchsia.ui.pointer/touch.fidl - fuchsia - Git at Google

 // Copyright 2020 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.pointer;

 const uint32 MAX_EVENT = 128;

 /// A method for a client to receive touch pointer events and respond in a
 /// global gesture disambiguation protocol.
 ///
 /// The position of a pointer event is defined in the context of a viewport,
 /// situated in the view. The dimensions of the view and viewport, and their
 /// spatial relationship (defined with a transform matrix), are supplied
 /// synchronously in a |ViewParameter| table. A view may retrieve a pointer's
 /// position in its local coordinate system by applying the viewport-to-view
 /// transform matrix.
 ///
 /// The viewport is embedded in an independent and stable coordinate system,
 /// suitable for interpreting pointer events in a scale-independent manner; a
 /// swipe will be observed at a constant scale, even under effects such as
 /// magnification or panning. However, other effects, such as enlargening the
 /// view's clip bounds, may trigger a change in the viewport extents.
 protocol TouchEventSource {
     /// A method for a client to receive touch pointer events.
     ///
     /// This call is formulated as a "hanging get" pattern: the client asks for
     /// a set of recent events, and receives them via the callback. This
     /// pull-based approach ensures that clients consume events at their own
     /// pace; events don't clog up the channel in an unbounded manner.
     ///
     /// Flow control. The caller is allowed at most one in-flight |Watch| call
     /// at a time; it is a logical error to have concurrent calls to |Watch|.
     /// Non-compliance results in channel closure.
     ///
     /// Client pacing. The server will dispatch events to the caller on a FIFO,
     /// lossless, best-effort basis, but the caller must allocate enough time to
     /// keep up with new events. An unresponsive client may be categorized as
     /// "App Not Responding" and targeted for channel closure.
     ///
     /// Responses. The gesture disambiguation scheme relies on the server
     /// receiving a |TouchResponse| for each |TouchEvent|.|TouchPointerSample|;
     /// non-sample events should return an empty |TouchResponse| table to the
     /// server. Responses for *previous* events are fed to the server on the
     /// *next* call of |Watch| [1]. Each element in the |responses| vector is
     /// interpreted as the pairwise response to the event in the previous
     /// |events| vector; the vector lengths must match.
     ///
     /// Initial response. The first call to |Watch| must be an empty vector.
     ///
     /// Event times. The timestamps on each event in the event vector are *not*
     /// guaranteed monotonic; pointer events from different devices may be
     /// injected into Scenic at different times. Generally, events from a single
     /// device are expected to have monotonically increasing timestamps.
     ///
     /// View parameters. Occasionally, changes in view or viewport require
     /// notifying the client. If a |TouchEvent| carries |ViewParameters|, these
     /// parameters apply to successive |TouchPointerSample|s until the next
     /// |ViewParameters|.
     ///
     /// [1] The hanging get pattern enables straightforward API evolution, but
     /// unfortunately does not admit an idiomatic matching of response to event.
     Watch(vector<TouchResponse>:MAX_EVENT responses) -> (vector<TouchEvent>:MAX_EVENT events);

     /// The gesture protocol allows a client to enact a "hold" on an event
     /// stream, to prevent resolution of event stream ownership, even after the
     /// stream has finished. This method updates the client's "hold" by
     /// replacing it with a response that allows ownership resolution to
     /// proceed.
     ///
     /// Flow control. The caller is allowed at most one |UpdateResponse| call
     /// per event stream, after the event stream has finished. It is a logical
     /// error to call |UpdateResponse| when a normal response is possible with
     /// the |Watch| call.
     ///
     /// Validity. This TouchResponse must not be another "hold" response, and
     /// the prior response is expected to be a "hold" response.
     UpdateResponse(TouchEventStreamId stream, TouchResponse response) -> ();
 };

 /// The self-sufficient, self-consistent collection of pointer-related data,
 /// sent from server to client.
 table TouchEvent {
     /// The time this event was observed.
     /// Required.
     1: zx.time timestamp;

     /// The parameters of the associated view and viewport, sufficient to
     /// correctly interpret the position, orientation, magnitude, and
     /// inter-event distance of pointer events dispatched to a view.
     /// - It is issued on connection and on change.
     2: ViewParameters view_parameters;

     /// A description of the pointer device, sufficient to correctly interpret
     /// the capabilities and usage intent of the device.
     /// - It is issued once per device.
     3: TouchDeviceInfo device_info;

     /// A description of each sampled data point in a pointer event stream.
     /// - It is issued on every sample in the pointer event stream.
     4: TouchPointerSample pointer_sample;

     /// The result of gesture disambiguation for a pointer event stream.
     /// - It is issued once per pointer event stream.
     5: TouchEventStreamInfo stream_info;

     /// An identifier to correlate this event's send/receive occurrence across
     /// component boundaries or abstraction layers.
     6: uint64 trace_flow_id;

     /// Certain clients may receive augmented data.
     7: fuchsia.ui.pointer.augment.LocalHitData local_hit_data;
 };

 /// Information about a device that issues touch event streams.
 table TouchDeviceInfo {
     /// An identifier for the touch device that issues touch event streams.
     /// A device may own multiple pointers, each with its own pointer id.
     /// Required.
     1: uint32 id;
 };

 /// A unique identifier for a pointer event stream.
 struct TouchEventStreamId {
     /// An identifier for the pointer device that issues pointer event streams.
     /// A device may own multiple pointers, each with its own |pointer_id|.
     uint32 device_id;

     /// An identifier of the pointer that issued this event. It is unique only
     /// to a specific |device_id|. Each (device_id, pointer_id) pair issues at
     /// most one pointer event stream at a time.
     uint32 pointer_id;

     /// An identifier of the pointer event stream. It is unique only to a
     /// specific (device_id, pointer_id) pair.
     uint32 stream_id;
 };

 /// A description of each sampled data point in a pointer event stream.
 /// All fields are required.
 table TouchPointerSample {
     /// The unique stream identifier that this pointer sample belongs to.
     1: TouchEventStreamId stream;

     /// The state of this event in the pointer event stream's state machine.
     2: EventPhase phase;

     /// The position of this event, in the viewport's coordinate system.
     3: Point2 position_in_viewport;
 };

 /// The status of a pointer event stream, sent from server to client.
 struct TouchEventStreamInfo {
     /// The unique stream identifier that this pointer sample belongs to.
     TouchEventStreamId stream;

     /// The pointer event stream's disposition, sent from server to client.
     TouchEventStreamStatus status;
 };

 /// A description of the touch event stream's relationship to this client.
 enum TouchEventStreamStatus {
     /// The client has been denied ownership of the event stream.
     DENIED = 1;

     /// The client has been granted ownership of the event stream.
     GRANTED = 2;
 };

 /// A feedback event per |Event|, sent from client to server.
 ///
 /// Only |TouchPointerSample| requires a |TouchResponseType|; for other events, an empty
 /// |Response| table is sent to the server.
 table TouchResponse {
     /// The event stream disposition that a client responds with for a given
     /// |TouchPointerSample|.
     1: TouchResponseType response_type;

     /// An identifier to correlate this response's send/receive occurrence across
     /// component boundaries or abstraction layers.
     2: uint64 trace_flow_id;
 };

 /// The possible event stream dispositions that a client can respond with to a
 /// given |TouchPointerSample|. Used as part of a gesture disambiguation scheme.
 ///
 /// The responses revolve around the idea of an ownership claim on a pointer event
 /// stream (i.e., current and future events of that event stream). Clients may
 /// assert a claim of ownership on the current event stream, but only one
 /// client's claim is granted by the server; other clients' claims are denied.
 enum TouchResponseType {
     /// The client has no further interest in this event stream; it declines
     /// ownership of the event stream. The client will stop receiving events
     /// from the pointer event stream.
     NO = 1;

     /// The client is interested in this event stream, but needs to see more
     /// events to decide; the client has not yet claimed ownership of the event
     /// stream.
     MAYBE = 2;

     /// The client is interested in this event stream, but needs to see more
     /// events to decide; the client has not yet claimed ownership of the event
     /// stream. During ownership resolution, it exerts its priority over
     /// lower-priority "maybe" claims, but always loses to a "yes" claim.
     MAYBE_PRIORITY = 3;

     /// The client is interested in this event stream, but needs to see more
     /// events to decide; the client has not yet claimed ownership of the event
     /// stream. Moreover, it suppresses lower-priority claims that try to
     /// resolve stream ownership.
     MAYBE_SUPPRESS = 4;

     /// The client is interested in this event stream, but needs to see more
     /// events to decide; the client has not yet claimed ownership of the event
     /// stream. Moreover, it suppresses lower-priority claims that try to
     /// resolve stream ownership. During ownership resolution, it exerts its
     /// priority over lower-priority "maybe" claims, but always loses to a "yes"
     /// claim.
     MAYBE_PRIORITY_SUPPRESS = 5;

     /// The client is interested in this event stream, but needs to see a
     /// subsequent event stream to decide; the client has not yet claimed
     /// ownership of the event stream. It prevents ownership resolution when the
     /// stream ends.
     HOLD = 6;

     /// The client is interested in this event stream, but needs to see a
     /// subsequent event stream to decide; the client has not yet claimed
     /// ownership of the event stream. It prevents ownership resolution when the
     /// stream ends. Moreover, it suppresses lower-priority claims that try to
     /// resolve stream ownership.
     HOLD_SUPPRESS = 7;

     /// The client wishes exclusive access to the remaining events in this event
     /// stream; it claims ownership of the event stream (but that claim may or
     /// may not be granted). During ownership resolution, it yields its priority
     /// to lower-priority "yes" claims.
     YES = 8;

     /// The client wishes exclusive access to the remaining events in this event
     /// stream; it claims ownership of the event stream (but that claim may or
     /// may not be granted). During ownership resolution, it exerts its priority
     /// over lower-priority "yes" claims.
     YES_PRIORITY = 9;
 };
	// Copyright 2020 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.pointer;

	const uint32 MAX_EVENT = 128;

	/// A method for a client to receive touch pointer events and respond in a
	/// global gesture disambiguation protocol.
	///
	/// The position of a pointer event is defined in the context of a viewport,
	/// situated in the view. The dimensions of the view and viewport, and their
	/// spatial relationship (defined with a transform matrix), are supplied
	/// synchronously in a \|ViewParameter\| table. A view may retrieve a pointer's
	/// position in its local coordinate system by applying the viewport-to-view
	/// transform matrix.
	///
	/// The viewport is embedded in an independent and stable coordinate system,
	/// suitable for interpreting pointer events in a scale-independent manner; a
	/// swipe will be observed at a constant scale, even under effects such as
	/// magnification or panning. However, other effects, such as enlargening the
	/// view's clip bounds, may trigger a change in the viewport extents.
	protocol TouchEventSource {
	/// A method for a client to receive touch pointer events.
	///
	/// This call is formulated as a "hanging get" pattern: the client asks for
	/// a set of recent events, and receives them via the callback. This
	/// pull-based approach ensures that clients consume events at their own
	/// pace; events don't clog up the channel in an unbounded manner.
	///
	/// Flow control. The caller is allowed at most one in-flight \|Watch\| call
	/// at a time; it is a logical error to have concurrent calls to \|Watch\|.
	/// Non-compliance results in channel closure.
	///
	/// Client pacing. The server will dispatch events to the caller on a FIFO,
	/// lossless, best-effort basis, but the caller must allocate enough time to
	/// keep up with new events. An unresponsive client may be categorized as
	/// "App Not Responding" and targeted for channel closure.
	///
	/// Responses. The gesture disambiguation scheme relies on the server
	/// receiving a \|TouchResponse\| for each \|TouchEvent\|.\|TouchPointerSample\|;
	/// non-sample events should return an empty \|TouchResponse\| table to the
	/// server. Responses for previous events are fed to the server on the
	/// next call of \|Watch\| [1]. Each element in the \|responses\| vector is
	/// interpreted as the pairwise response to the event in the previous
	/// \|events\| vector; the vector lengths must match.
	///
	/// Initial response. The first call to \|Watch\| must be an empty vector.
	///
	/// Event times. The timestamps on each event in the event vector are not
	/// guaranteed monotonic; pointer events from different devices may be
	/// injected into Scenic at different times. Generally, events from a single
	/// device are expected to have monotonically increasing timestamps.
	///
	/// View parameters. Occasionally, changes in view or viewport require
	/// notifying the client. If a \|TouchEvent\| carries \|ViewParameters\|, these
	/// parameters apply to successive \|TouchPointerSample\|s until the next
	/// \|ViewParameters\|.
	///
	/// [1] The hanging get pattern enables straightforward API evolution, but
	/// unfortunately does not admit an idiomatic matching of response to event.
	Watch(vector<TouchResponse>:MAX_EVENT responses) -> (vector<TouchEvent>:MAX_EVENT events);

	/// The gesture protocol allows a client to enact a "hold" on an event
	/// stream, to prevent resolution of event stream ownership, even after the
	/// stream has finished. This method updates the client's "hold" by
	/// replacing it with a response that allows ownership resolution to
	/// proceed.
	///
	/// Flow control. The caller is allowed at most one \|UpdateResponse\| call
	/// per event stream, after the event stream has finished. It is a logical
	/// error to call \|UpdateResponse\| when a normal response is possible with
	/// the \|Watch\| call.
	///
	/// Validity. This TouchResponse must not be another "hold" response, and
	/// the prior response is expected to be a "hold" response.
	UpdateResponse(TouchEventStreamId stream, TouchResponse response) -> ();
	};

	/// The self-sufficient, self-consistent collection of pointer-related data,
	/// sent from server to client.
	table TouchEvent {
	/// The time this event was observed.
	/// Required.
	1: zx.time timestamp;

	/// The parameters of the associated view and viewport, sufficient to
	/// correctly interpret the position, orientation, magnitude, and
	/// inter-event distance of pointer events dispatched to a view.
	/// - It is issued on connection and on change.
	2: ViewParameters view_parameters;

	/// A description of the pointer device, sufficient to correctly interpret
	/// the capabilities and usage intent of the device.
	/// - It is issued once per device.
	3: TouchDeviceInfo device_info;

	/// A description of each sampled data point in a pointer event stream.
	/// - It is issued on every sample in the pointer event stream.
	4: TouchPointerSample pointer_sample;

	/// The result of gesture disambiguation for a pointer event stream.
	/// - It is issued once per pointer event stream.
	5: TouchEventStreamInfo stream_info;

	/// An identifier to correlate this event's send/receive occurrence across
	/// component boundaries or abstraction layers.
	6: uint64 trace_flow_id;

	/// Certain clients may receive augmented data.
	7: fuchsia.ui.pointer.augment.LocalHitData local_hit_data;
	};

	/// Information about a device that issues touch event streams.
	table TouchDeviceInfo {
	/// An identifier for the touch device that issues touch event streams.
	/// A device may own multiple pointers, each with its own pointer id.
	/// Required.
	1: uint32 id;
	};

	/// A unique identifier for a pointer event stream.
	struct TouchEventStreamId {
	/// An identifier for the pointer device that issues pointer event streams.
	/// A device may own multiple pointers, each with its own \|pointer_id\|.
	uint32 device_id;

	/// An identifier of the pointer that issued this event. It is unique only
	/// to a specific \|device_id\|. Each (device_id, pointer_id) pair issues at
	/// most one pointer event stream at a time.
	uint32 pointer_id;

	/// An identifier of the pointer event stream. It is unique only to a
	/// specific (device_id, pointer_id) pair.
	uint32 stream_id;
	};

	/// A description of each sampled data point in a pointer event stream.
	/// All fields are required.
	table TouchPointerSample {
	/// The unique stream identifier that this pointer sample belongs to.
	1: TouchEventStreamId stream;

	/// The state of this event in the pointer event stream's state machine.
	2: EventPhase phase;

	/// The position of this event, in the viewport's coordinate system.
	3: Point2 position_in_viewport;
	};

	/// The status of a pointer event stream, sent from server to client.
	struct TouchEventStreamInfo {
	/// The unique stream identifier that this pointer sample belongs to.
	TouchEventStreamId stream;

	/// The pointer event stream's disposition, sent from server to client.
	TouchEventStreamStatus status;
	};

	/// A description of the touch event stream's relationship to this client.
	enum TouchEventStreamStatus {
	/// The client has been denied ownership of the event stream.
	DENIED = 1;

	/// The client has been granted ownership of the event stream.
	GRANTED = 2;
	};

	/// A feedback event per \|Event\|, sent from client to server.
	///
	/// Only \|TouchPointerSample\| requires a \|TouchResponseType\|; for other events, an empty
	/// \|Response\| table is sent to the server.
	table TouchResponse {
	/// The event stream disposition that a client responds with for a given
	/// \|TouchPointerSample\|.
	1: TouchResponseType response_type;

	/// An identifier to correlate this response's send/receive occurrence across
	/// component boundaries or abstraction layers.
	2: uint64 trace_flow_id;
	};

	/// The possible event stream dispositions that a client can respond with to a
	/// given \|TouchPointerSample\|. Used as part of a gesture disambiguation scheme.
	///
	/// The responses revolve around the idea of an ownership claim on a pointer event
	/// stream (i.e., current and future events of that event stream). Clients may
	/// assert a claim of ownership on the current event stream, but only one
	/// client's claim is granted by the server; other clients' claims are denied.
	enum TouchResponseType {
	/// The client has no further interest in this event stream; it declines
	/// ownership of the event stream. The client will stop receiving events
	/// from the pointer event stream.
	NO = 1;

	/// The client is interested in this event stream, but needs to see more
	/// events to decide; the client has not yet claimed ownership of the event
	/// stream.
	MAYBE = 2;

	/// The client is interested in this event stream, but needs to see more
	/// events to decide; the client has not yet claimed ownership of the event
	/// stream. During ownership resolution, it exerts its priority over
	/// lower-priority "maybe" claims, but always loses to a "yes" claim.
	MAYBE_PRIORITY = 3;

	/// The client is interested in this event stream, but needs to see more
	/// events to decide; the client has not yet claimed ownership of the event
	/// stream. Moreover, it suppresses lower-priority claims that try to
	/// resolve stream ownership.
	MAYBE_SUPPRESS = 4;

	/// The client is interested in this event stream, but needs to see more
	/// events to decide; the client has not yet claimed ownership of the event
	/// stream. Moreover, it suppresses lower-priority claims that try to
	/// resolve stream ownership. During ownership resolution, it exerts its
	/// priority over lower-priority "maybe" claims, but always loses to a "yes"
	/// claim.
	MAYBE_PRIORITY_SUPPRESS = 5;

	/// The client is interested in this event stream, but needs to see a
	/// subsequent event stream to decide; the client has not yet claimed
	/// ownership of the event stream. It prevents ownership resolution when the
	/// stream ends.
	HOLD = 6;

	/// The client is interested in this event stream, but needs to see a
	/// subsequent event stream to decide; the client has not yet claimed
	/// ownership of the event stream. It prevents ownership resolution when the
	/// stream ends. Moreover, it suppresses lower-priority claims that try to
	/// resolve stream ownership.
	HOLD_SUPPRESS = 7;

	/// The client wishes exclusive access to the remaining events in this event
	/// stream; it claims ownership of the event stream (but that claim may or
	/// may not be granted). During ownership resolution, it yields its priority
	/// to lower-priority "yes" claims.
	YES = 8;

	/// The client wishes exclusive access to the remaining events in this event
	/// stream; it claims ownership of the event stream (but that claim may or
	/// may not be granted). During ownership resolution, it exerts its priority
	/// over lower-priority "yes" claims.
	YES_PRIORITY = 9;
	};