// 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.gfx;

/// Reports metrics information.
/// This event type is only reported for node resources.
const kMetricsEventMask uint32 = 1;
const kSizeChangeHintEventMask uint32 = 2;

/// These are all of the types of events which can be reported by a `Session`.
/// Use `SetEventMaskCmd` to enable event delivery for a resource.
type Event = strict union {
    /// Events which are controlled by a mask.
    1: metrics MetricsEvent;

    2: size_change_hint SizeChangeHintEvent;

    /// Events which are always delivered, regardless of mask.
    3: import_unbound ImportUnboundEvent;
    4: view_connected ViewConnectedEvent;
    5: view_disconnected ViewDisconnectedEvent;
    6: view_holder_disconnected ViewHolderDisconnectedEvent;
    7: view_attached_to_scene ViewAttachedToSceneEvent;
    8: view_detached_from_scene ViewDetachedFromSceneEvent;
    9: view_properties_changed ViewPropertiesChangedEvent;
   10: view_state_changed ViewStateChangedEvent;
   11: view_holder_connected ViewHolderConnectedEvent;
};

/// Provides rendering target metrics information about the specified node.
///
/// This event is delivered when the following conditions are true:
/// - The node is a descendant of a `Scene`.
/// - The node has `kMetricsEventMask` set to an enabled state.
/// - The node's metrics have changed since they were last delivered, or since
///   `kMetricsEventMask` transitioned from a disabled state to an enabled state.
///
/// Subscribe to this event to receive information about the scale factors you
/// should apply when generating textures for your nodes.
type MetricsEvent = struct {
    node_id uint32;
    metrics Metrics;
};

/// Delivered in response to a size change hint from a parent node
/// (SendSizeChangeHintCmd).
///
/// This event is delivered when the following conditions are true:
/// - The node has `kSizeChangeEventMask` set to an enabled state.
/// - A parent node has sent a SendSizeChangeHintCmd.
///
/// Subscribe to this event to receive information about how large textures you
/// will need in the near future for your nodes. The canonical use case is to
/// pre-allocate memory to avoid repeated re-allocations.
type SizeChangeHintEvent = struct {
    node_id uint32;
    width_change_factor float32;
    height_change_factor float32;
};

/// Delivered when the imported resource with the given ID is no longer bound to
/// its host resource, or if the imported resource can not be bound because
/// the host resource is not available.
type ImportUnboundEvent = struct {
    resource_id uint32;
};

/// Delivered to a ViewHolder's Session when its peer View is connected.
type ViewConnectedEvent = struct {
    view_holder_id uint32;
};

/// Delivered to a ViewHolder's Session when its peer View is disconnected or
/// destroyed.
///
/// If the View is destroyed before the connection is established, then this
/// event will be delivered immediately when the ViewHolder attempts to connect.
type ViewDisconnectedEvent = struct {
    view_holder_id uint32;
};

/// Delivered to a View's Session when its peer ViewHolder is disconnected or
/// destroyed.
///
/// If the ViewHolder is destroyed before the connection is established, then
/// this event will be delivered immediately when the View attempts to connect.
type ViewHolderDisconnectedEvent = struct {
    view_id uint32;
};

/// Delivered to a View's Session when its peer ViewHolder is connected.
///
/// If the ViewHolder is destroyed before the connection is established, then
/// this event will not be delivered.
type ViewHolderConnectedEvent = struct {
    view_id uint32;
};

/// Delivered to a View's Session when the parent ViewHolder for the given View
/// becomes a part of a Scene.
///
/// A ViewHolder is considered to be part of a Scene if there is an unbroken
/// chain of parent-child relationships between the Scene node and the
/// ViewHolder node.
type ViewAttachedToSceneEvent = struct {
    view_id uint32;
    properties ViewProperties;
};

/// Delivered to a View's Session when the parent ViewHolder for the given View
/// is no longer part of a scene.
///
/// This can happen if the ViewHolder is detached directly from the scene, or
/// if one of its parent nodes is.
///
/// A ViewHolder is considered to be part of a Scene if there is an unbroken
/// chain of parent-child relationships between the Scene node and the
/// ViewHolder node.
type ViewDetachedFromSceneEvent = struct {
    view_id uint32;
};

/// Delivered when the parent ViewHolder for the given View makes a change to
/// the View's properties.
type ViewPropertiesChangedEvent = struct {
    view_id uint32;
    properties ViewProperties;
};

/// Delivered to a ViewHolder's Session when its peer View's state has changed.
type ViewStateChangedEvent = struct {
    view_holder_id uint32;
    state ViewState;
};