138 lines
7.1 KiB
C#
138 lines
7.1 KiB
C#
/*
|
|
* Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
* All rights reserved.
|
|
*
|
|
* Licensed under the Oculus SDK License Agreement (the "License");
|
|
* you may not use the Oculus SDK except in compliance with the License,
|
|
* which is provided at the time of installation or download, or which
|
|
* otherwise accompanies this software in either electronic or hard copy form.
|
|
*
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* https://developer.oculus.com/licenses/oculussdk/
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, the Oculus SDK
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
using System;
|
|
using UnityEngine;
|
|
|
|
namespace Oculus.Interaction
|
|
{
|
|
/// <summary>
|
|
/// Enumeration of the types of occurrences a <see cref="PointerEvent"/> can represent.
|
|
/// </summary>
|
|
public enum PointerEventType
|
|
{
|
|
Hover,
|
|
Unhover,
|
|
Select,
|
|
Unselect,
|
|
Move,
|
|
Cancel
|
|
}
|
|
|
|
/// <summary>
|
|
/// Created and emitted to encapsulate the relevant information of a "pointer interaction," which is an interaction the user
|
|
/// conducted by conceptually "pointing at" something. This event contains information about the interactor (canonically a
|
|
/// <see cref="PointerInteractor{TInteractor, TInteractable}"/>) which originated the interaction, what type of interaction it was,
|
|
/// where it occurred, and relevant ancillary data.
|
|
/// </summary>
|
|
public struct PointerEvent : IEvent
|
|
{
|
|
/// <summary>
|
|
/// The <see cref="IInteractorView.Identifier"/> associated with interactor which originated the interaction represented by this
|
|
/// event. This identifier is uniquely associated with a single interactor instance in the experience.
|
|
/// </summary>
|
|
public int Identifier { get; }
|
|
|
|
/// <summary>
|
|
/// A unique value associated with this specific event, meaning the semantic occurrence at a specific point in time which
|
|
/// motivated the creation of this data object.
|
|
/// </summary>
|
|
public UInt64 EventId { get; }
|
|
|
|
/// <summary>
|
|
/// A characterization of the type of interaction this event represents. Each PointerEvent can represent only one simple
|
|
/// interaction, and complex interactions (for example, an interactable being deselected by one interactor in order to be selected
|
|
/// by another) must consequently be represented by multiple sequential PointerEvents.
|
|
/// </summary>
|
|
public PointerEventType Type { get; }
|
|
|
|
/// <summary>
|
|
/// The world-space position associated with the represented interaction. The precise meaning of this <see cref="Pose"/> varies
|
|
/// based on the interaction <see cref="Type"/> and what kind of interaction it is: a <see cref="PokeInteractor"/>'s
|
|
/// <see cref="PointerEventType.Select"/> might designate the pose of the interactor at the moment of selection, a
|
|
/// <see cref="GrabInteractor"/> <see cref="PointerEventType.Move"/> might designate the expected pose of the interactable based on
|
|
/// the behavior of the relevant <see cref="IMovement"/> in the most recent processing frame, etc. PointerEvent thus does not specify
|
|
/// a unique, precise contract for this value, and the responsibility for interpreting this pose correctly belongs to the handler.
|
|
/// </summary>
|
|
public Pose Pose { get; }
|
|
|
|
/// <summary>
|
|
/// A generic metadata property used for a variety of purposes in Interaction SDK logic. Though this property
|
|
/// is public, it has no formal contract, and consequently it is generally not safe to assume that any specific
|
|
/// piece of information is available through this property on any instance at any time.
|
|
/// </summary>
|
|
public object Data { get; }
|
|
|
|
/// <summary>
|
|
/// Constructor for new PointerEvents.
|
|
/// </summary>
|
|
/// <param name="identifier">The <see cref="IInteractorView.Identifier"/> of the originating interactor</param>
|
|
/// <param name="type">The <see cref="PointerEventType"/> which most accurately characterizes the represented interaction</param>
|
|
/// <param name="pose">The world space position and orientation associated with this interaction</param>
|
|
/// <param name="data">Contractually undefined metadata</param>
|
|
public PointerEvent(int identifier, PointerEventType type, Pose pose, object data = null)
|
|
{
|
|
Identifier = identifier;
|
|
EventId = ++_nextEventId;
|
|
// At 100 pointer events per frame, this field is expected not to overflow for more than fifty million years, so hitting this
|
|
// assert suggests either a massive overproduction of pointer events or memory corruption.
|
|
Debug.Assert(_nextEventId != UInt64.MaxValue);
|
|
Type = type;
|
|
Pose = pose;
|
|
Data = data;
|
|
}
|
|
|
|
private static UInt64 _nextEventId = 0;
|
|
}
|
|
|
|
/// <summary>
|
|
/// This interface specifies that an implementing type is a source for <see cref="PointerEvent"/>s, which are raised in response
|
|
/// to certain actions which reflect user intent by "pointing" at something. Events raised by IPointables are both consumed and
|
|
/// propagated by <see cref="IPointableElement"/>s.
|
|
/// </summary>
|
|
public interface IPointable
|
|
{
|
|
/// <summary>
|
|
/// Event raised when the IPointable undergoes any of the state changes representable by <see cref="PointerEvent"/>s:
|
|
/// hover, unhover, selection, etc. These behaviors map readily to behaviours common among 2D UIs (hover, unhover, etc.).
|
|
/// </summary>
|
|
event Action<PointerEvent> WhenPointerEventRaised;
|
|
}
|
|
|
|
/// <summary>
|
|
/// This interface specifies that an implementing type is a recipient of <see cref="PointerEvent"/>s and is thus conceptually
|
|
/// something, "to which one can point." Note that IPointableElement is (as an <see cref="IPointable"/>) both an originator of
|
|
/// and a consumer of <see cref="PointerEvent"/>s; this manifests the common Interaction SDK pattern that
|
|
/// <see cref="PointerEvent"/>s are created by the instrument which _does_ the pointing, are received by the target to which one
|
|
/// points, and are then forwarded by that target to additional consumers.
|
|
/// </summary>
|
|
public interface IPointableElement : IPointable
|
|
{
|
|
/// <summary>
|
|
/// Instructs the IPointableElement to handle a provided <see cref="PointerEvent"/> which represents a user action of
|
|
/// "pointing" something at this IPointableElement. This processing will typically result in the processed
|
|
/// <see cref="PointerEvent"/> being re-emitted after processing by the IPointableElement as part of its role as an
|
|
/// <see cref="IPointable"/>.
|
|
/// </summary>
|
|
/// <param name="evt">The <see cref="PointerEvent"/> to be processed</param>
|
|
void ProcessPointerEvent(PointerEvent evt);
|
|
}
|
|
}
|