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

// Primitives express the geometry of the scene, such as quads and references
// to embedded scenes.  Primitives are arranged hierarchically as nodes,
// each with an associated transformation matrix.

[DartPackage="mojo_services"]
module mojo.gfx.composition;

import "mojo/services/geometry/interfaces/geometry.mojom";
import "mojo/services/gfx/composition/interfaces/hit_tests.mojom";

// Nodes express the geometry and content of the scene, such as images and
// references to embedded scenes.  Nodes are arranged to form a directed
// acyclic graph of drawing commands.
//
// The node graph is processed in pre-order traversal.  Starting from the
// root, the compositor applies the transformation, clip, recursively
// processes the node's children according to the node's combinator rule,
// then applies the node's own operation.
//
// BLOCKED NODES
//
// Due to the asynchronous nature of the system, it may happen that some
// nodes cannot be processed immediately at drawing time because they require
// access to certain resources which are not available, such as a specific
// version of a scene which has yet to be produced by some other application.
//
// When a node cannot be drawn due to an unsatisfied dependency, it is
// said to be "blocked".  Blocked nodes prevent rendering of the entire
// subgraph below them.
//
// NODE COMBINATORS
//
// Node combinator rules describe what should happen when a node which is
// otherwise unblocked has one or more blocked children.
//
// With the |MERGE| combinator, the children of a node are all drawn in
// sequence if none of them are blocked, otherwise the node itself is
// blocked.  This is the default.
//
// With the |PRUNE| combinator, the children of a node are all drawn in
// sequence while skipping over any of them which are blocked.  Blocked
// children will not appear in the output.
//
// With the |FALLBACK| combinator, the first unblocked child of a node is
// drawn and the remaining nodes are ignored.  If the node has children
// and all of them are blocked then the node itself is blocked.
//
// Combinators make it possible to express complex rules such as substituting
// missing content for an earlier version of that content or for a placeholder
// if not available.
//
// TIPS
//
// 1. Reuse nodes when possible to reduce the size of the graph.  Consider
//    using LayerNodeOps to flatten common elements to a texture which can
//    be redrawn efficiently in many places.
//
// 2. Insert PRUNE or FALLBACK nodes in places where blocking is likely to
//    occur, such as when embedding scenes produced by other applications.
//    Provide alternate content where possible.
//
struct Node {
  // The combinator specifies how child nodes are processed.
  enum Combinator {
    // All children are drawn in sequence, blocking if any are blocked.
    MERGE,
    // All children are drawn in sequence, skipping any that are blocked.
    PRUNE,
    // The first unblocked node is drawn, blocking if there are children
    // and all of them are blocked.
    FALLBACK,
  };

  // The forward transformation from the node's content space to its
  // containing node's content space.  If null, an identity transformation
  // is assumed.
  //
  // For example, if you want to translate the content of the node so that
  // it is drawn at X = 100 relative to its containing node's origin, simply
  // set a transformation matrix with the X translation component equal to 100.
  // Take care not to specify the inverse transform by mistake.
  mojo.Transform? content_transform;

  // The clip rectangle to apply to this node's content and to its children
  // in content space in addition to any clipping performed by the container.
  // If null, the node does not apply any clipping of its own.
  mojo.Rect? content_clip;

  // The hit test id to report if anything within the node is hit.
  // Use |kHitIdNone| if the node should not be hit tested.
  //
  // TODO(jeffbrown): This scheme is probably too naive.
  uint32 hit_id = kHitIdNone;

  // The Combinator to apply when processing the children of this node.
  Combinator combinator = Combinator.MERGE;

  // The ids of the children of this node.
  // It is an error to specify a node id that does not refer to a valid
  // node; the compositor will close the connection when the scene
  // is published.
  // If a cycle is introduced then the node will be considered to be blocked
  // at the point where recursion occurs.  A subsequent rearrangement of
  // scenes which removes the cycle will unblock the node.
  array<uint32>? child_node_ids;

  // The drawing operation to apply when processing this node.
  // If null, no drawing operation occurs at this node.
  NodeOp? op;
};

// A drawing operation to apply when processing the node.
union NodeOp {
  RectNodeOp rect;
  ImageNodeOp image;
  SceneNodeOp scene;
  LayerNodeOp layer;
  // TODO(jeffbrown): Color filters.
};

// Fills a rectangle with a solid color.
struct RectNodeOp {
  // The rectangle to fill in content space.
  mojo.Rect content_rect;

  // The rectangle's color.
  Color color;
};

// Draws an image at the specified location.
//
// The node containing this operation will be blocked if the image resource
// is not ready for use at draw time.
struct ImageNodeOp {
  // The rectangle in which to draw the image in content space.
  mojo.Rect content_rect;

  // The portion of the image to draw.
  // If null, draws the entire image.
  mojo.Rect? image_rect;

  // The resource id of a valid |MailboxTextureResource| to draw.
  // It is an error to specify a resource id that does not refer to an image
  // resource; the compositor will close the connection when the scene
  // is published.
  uint32 image_resource_id;

  // The blending parameters.  If null, uses the default values specified
  // in the |Blend| structure declaration.
  Blend? blend;
};

// Draws a scene.
//
// A scene operation embeds another scene at this point in the scene graph.
// It has essentially the same effect as drawing the root node of the
// referenced scene and drawing it as if it were a child of this node.
//
// The node containing this operation will be blocked if the specified
// version of the scene is not ready for use at draw time or if it too
// is blocked.
//
// It is often useful to wrap this node with a |LayerNodeOp| when blending
// the scene with other content.
struct SceneNodeOp {
  // The resource id of a valid |SceneResource| to link into the scene.
  // It is an error to specify a resource id that does not refer to a scene
  // resource; the compositor will close the connection when the scene
  // is published.
  // If a cycle is introduced then the node will be considered to be blocked
  // at the point where recursion occurs.  A subsequent rearrangement of
  // scenes which removes the cycle will unblock the node.
  uint32 scene_resource_id;

  // The version of the scene that we would like to reference.
  // Use |kSceneVersionNone| to request the most recently published
  // version of the scene if synchronization is unimportant.
  uint32 scene_version = 0; // kSceneVersionNone
};

// Draws a layer.
//
// Conceptually, this operation has the effect of drawing the children of
// the node to a temporary buffer of the specified size which is then
// composited in place like an image.  This is useful for ensuring
// correct blending of layered content.
struct LayerNodeOp {
  // The size of the layer to create.
  mojo.Size layer_size;

  // The blending parameters.  If null, uses the default values specified
  // in the |Blend| structure declaration.
  Blend? blend;
};

// Specifies a color to draw.
// TODO(jeffbrown): This is silly but unambiguous for prototyping.
// Make it less silly.
struct Color {
  uint8 red;
  uint8 green;
  uint8 blue;
  uint8 alpha;
};

// Specifies how blending should take place.
struct Blend {
  // The opacity for composition in a range from 0 (fully transparent)
  // to 255 (fully opaque).
  uint8 alpha = 255;

  // TODO(jeffbrown): Blend modes and texture filtering.
};