// Copyright (C) 2015 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// 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.

@handle type string ApiId
@handle type string AtomStreamId
@handle type string BinaryId
@handle type string CaptureId
@handle type string DeviceId
@handle type string HierarchyId
@handle type string ImageInfoId
@handle type string MemoryInfoId
@handle type string SchemaId
@handle type string TimingInfoId

// Import imports capture data emitted by the graphics spy, returning the new
// capture identifier.
cmd CaptureId Import(string name, u8[] Data) { return ? }

// GetCaptures returns the full list of capture identifiers avaliable on the
// server.
cmd CaptureId[] GetCaptures() { return ? }

// GetDevices returns the full list of replay devices avaliable to the server.
// These include local replay devices and any connected Android devices.
// This list may change over time, as devices are connected and disconnected.
cmd DeviceId[] GetDevices() { return ? }

// GetState returns an identifier to a binary blob containing the graphics state
// immediately following the atom after.
// The binary blob can be fetched with a call to ResolveBinary, and decoded
// using the capture's schema.
cmd BinaryId GetState(CaptureId capture, u64 after)
{ return ? }

// GetHierarchy returns the atom hierarchy identifier for the given capture.
// Currently there is only one hierarchy per capture, but this is likely to
// change in the future.
cmd HierarchyId GetHierarchy(CaptureId capture)
{ return ? }

// GetMemoryInfo returns the MemoryInfo identifier describing the memory state
// for the given capture and range, immediately following the atom
// after.
cmd MemoryInfoId GetMemoryInfo(CaptureId capture, u64 after, MemoryRange rng)
{ return ? }

// GetFramebufferColor returns the ImageInfo identifier describing the bound
// color buffer for the given device, capture and graphics API immediately
// following the atom after. The provided RenderSettings structure can be used
// to adjust maximum desired dimensions of the image, as well as applying debug
// visualizations.
cmd ImageInfoId GetFramebufferColor(DeviceId       device,
                                    CaptureId      capture,
                                    ApiId          api,
                                    u64            after,
                                    RenderSettings settings)
{ return ? }

// GetFramebufferDepth returns the ImageInfo identifier describing the bound
// depth buffer for the given device, capture and graphics API immediately
// following the atom after.
cmd ImageInfoId GetFramebufferDepth(DeviceId  device,
                                    CaptureId capture,
                                    ApiId     api,
                                    u64       after)
{ return ? }

// GetTimingInfo performs timings of the given capture on the given device,
// returning an identifier to the results.
// This function is experimental and will change signature.
cmd TimingInfoId GetTimingInfo(DeviceId   device,
                               CaptureId  capture,
                               TimingMask mask)
{ return ? }

// PrerenderFramebuffers renders the framebuffer contents after each of the
// given atoms of interest in the given capture on the given device for the
// given graphics API, resized to fit within the given dimensions while keeping
// the respective framebuffers original aspect ratio. This function doesn't
// return any data, as it is used to pre-populate the cache of framebuffer
// thumbnails that later get queried by the client. This function is
// experimental and may change signature.
cmd BinaryId PrerenderFramebuffers(DeviceId   device,
                                   CaptureId  capture,
                                   ApiId      api,
                                   u32        width,
                                   u32        height,
                                   u64[]      atomIds)
{ return ? }

// ReplaceAtom creates and new capture based on an existing capture, but with
// a single atom replaced.
cmd CaptureId ReplaceAtom(CaptureId capture,
                          u64       atomId,
                          u16       atomType,
                          Binary    data)
{ return ? }

cmd AtomStream         ResolveAtomStream(AtomStreamId id) { return ? }
cmd Binary             ResolveBinary(BinaryId id) { return ? }
cmd Capture            ResolveCapture(CaptureId id) { return ? }
cmd Device             ResolveDevice(DeviceId id) { return ? }
cmd Hierarchy          ResolveHierarchy(HierarchyId id) { return ? }
cmd ImageInfo          ResolveImageInfo(ImageInfoId id) { return ? }
cmd MemoryInfo         ResolveMemoryInfo(MemoryInfoId id) { return ? }
cmd Schema             ResolveSchema(SchemaId id) { return ? }
cmd TimingInfo         ResolveTimingInfo(TimingInfoId id) { return ? }

// Device describes replay target avaliable to the server.
class Device {
  string Name             // The name of the device. i.e. "Bob's phone"
  string Model            // The model of the device. i.e. "Nexus 5"
  string OS               // The operating system of the device. i.e. "Android 5.0"
  u8     PointerSize      // Size in bytes of a pointer on the device's architecture.
  u8     PointerAlignment // Alignment in bytes of a pointer on the device's architecture.
  u64    MaxMemorySize    // The total amount of contiguous memory pre-allocated for replay.
  bool   RequiresShaderPatching // HACK. Will be removed.
}

// Capture describes single capture file held by the server.
class Capture {
  string              Name     // Name given to the capture. i.e. "KittyWorld"
  AtomStreamId        Atoms    // The identifier to the stream of atoms in this capture.
  ApiId[]             Apis     // List of graphics APIs used by this capture.
  SchemaId            Schema   // The schema used to decode types in this capture.
}

// Binary holds a blob of data.
class Binary {
  u8[] Data
}

// AtomStream holds a stream of atoms in binary form. The atoms can be unpacked
// using the capture's schema.
class AtomStream {
  u8[] Data // Encoded atom stream.
}

// Hierarchy holds the root to an AtomGroup hierarchy.
class Hierarchy {
  AtomGroup Root
}

// AtomGroup represents a named, contiguous span of atoms with support for
// sparse sub-groups. AtomGroups are used for expressing nested hierarchies of
// atoms formed from frame boundaries, draw call boundaries and user markers.
class AtomGroup {
  string            Name      // Name of this group.
  AtomRange         Range     // The span of atoms this group covers.
  AtomGroup[]       SubGroups // The list of sub-groups within this group.
}

// AtomRange describes a span of atoms in an AtomStream.
class AtomRange {
  u64 First // The index of the first atom in the range.
  u64 Count // The number of atoms in the range.
}

// MemoryInfo describes the state of a range of memory at a specific point in
// the atom stream. This structure is likely to change in the future.
class MemoryInfo {
  u8[]           Data    // The memory values for the span.
  MemoryRange[]  Stale   // The data ranges that have been observed but not current.
  MemoryRange[]  Current // The data ranges that were written to just before the observation.
  MemoryRange[]  Unknown // The data ranges that have never been observed.
}

// MemoryRange describes a range of memory.
class MemoryRange {
  u64 Base // The pointer to the first byte in the memory range.
  u64 Size // The size in bytes of the memory range.
}

// ImageInfo describes an image, such as a texture or framebuffer at a specific
// point in the atom stream.
class ImageInfo {
  ImageFormat Format // The format of the image.
  u32         Width  // The width of the image in pixels.
  u32         Height // The height of the image in pixels.
  BinaryId    Data   // The pixel data of the image.
}

// The enumerator of image formats. Will expand.
enum ImageFormat {
  RGBA8   = 0,
  Float32 = 1,
}

// TimingMask is a bitfield describing what should be timed.
// This is experimental and will change in the near future.
bitfield TimingMask {
  TimingPerCommand  = 0x1, // Time individual commands.
  TimingPerDrawCall = 0x2, // Time each draw call.
  TimingPerFrame    = 0x4, // Time each frame.
}

// TimingInfo holds the results of a resolved GetTimingInfo request.
// This is experimental and will change in the near future.
class TimingInfo {
  AtomTimer[]      PerCommand  // The timing results of each command.
  AtomRangeTimer[] PerDrawCall // The timing results of each draw call.
  AtomRangeTimer[] PerFrame    // The timing results of each frame.
}

// AtomTimer holds the timing information for a single atom.
// This is experimental and will change in the near future.
class AtomTimer {
  u64 AtomId      // The atom that was timed.
  u64 Nanoseconds // The time taken for that atom.
}

// AtomRangeTimer holds the timing information for a range of contiguous atoms.
// This is experimental and will change in the near future.
class AtomRangeTimer {
  u64 FromAtomId  // The first atom in the range that was timed.
  u64 ToAtomId    // The last atom in the range that was timed.
  u64 Nanoseconds // The time taken for all atoms in the range.
}

// RenderSettings contains settings and flags to be used in replaying and
// returning a bound render target's color buffer.
class RenderSettings {
  u32  MaxWidth  // The desired maximum width of the image. The returned image may be larger than this.
  u32  MaxHeight // The desired minimum height of the image. The returned image may be larger than this.
  bool Wireframe // True if the all geometry should be rendered as wireframe.
}

// The Schema describes all the array, map, enum, struct, class, atom and state
// types stored within the AtomStream and state. Clients use the Schema to know
// how to interpret these types.
class Schema {
  AtomInfo[]  Atoms // The schema description of all atoms in all APIs.
  ApiSchema[] Apis  // The per-API schema descriptions.
}

// ApiSchema describes the schema used by a single graphics API.
class ApiSchema {
  ApiId      Api   // The API identifier.
  StructInfo State // The state layout.
}

// TypeKind is the exhaustive list of all types supported by the schema.
enum TypeKind {
  // Primative types
  Bool               =  0,
  S8                 =  1,
  U8                 =  2,
  S16                =  3,
  U16                =  4,
  S32                =  5,
  U32                =  6,
  F32                =  7,
  S64                =  8,
  U64                =  9,
  F64                = 10,
  String             = 11,
  Enum               = 12,
  // Complex types
  Struct             = 14,
  Class              = 15,
  Array              = 16,
  StaticArray        = 17,
  Map                = 18,
  Pointer            = 19,
  Memory             = 20, // Currently unimplemented.
  Any                = 21, // Will be removed.
  ID                 = 22,
}

// TypeInfo is the base of all schema defined types.
@Interface class TypeInfo {
  string   Name // The name of the type.
  TypeKind Kind // The kind of the type.
}

// ArrayInfo describes an array instantiation.
class ArrayInfo : TypeInfo {
  TypeInfo* ElementType // The array's element type.
}

// StaticArrayInfo describes a static array instantiation.
class StaticArrayInfo : TypeInfo {
  TypeInfo*  ElementType // The array's element type.
  u32        Size        // The array's size.
}

// MapInfo describes a map instantiation.
class MapInfo : TypeInfo {
  TypeInfo* KeyType   // The map's key type.
  TypeInfo* ValueType // The map's value type.
}

// EnumInfo describes an enum type.
class EnumInfo : TypeInfo {
  EnumEntry[]  Entries // The list of enum entries.
  EnumInfo*[]  Extends // The list of enums this enum extends from. Will be removed.
}

// EnumEntry describes a single name-value entry in an enum.
class EnumEntry {
  string Name  // The name of the enum entry.
  u32    Value // The value of the enum entry. May be extended to u64.
}

// StructInfo describes the body of a single struct type.
class StructInfo : TypeInfo {
  FieldInfo*[] Fields // The list of fields in the struct.
}

// ClassInfo describes the body of a single class type.
class ClassInfo : TypeInfo {
  FieldInfo*[] Fields  // The list of fields in the class.
  ClassInfo*[] Extends // The list of classes this enum classes from. Likely to be removed.
}

// FieldInfo describes a single field entry in a class or struct.
class FieldInfo {
  string    Name // The name of the field.
  TypeInfo* Type // The type of the field.
}

// AtomInfo describes a single Atom type.
class AtomInfo {
  ApiId                 Api               // The graphics API that this Atom belongs to.
  u16                   Type              // The atom's unique type identifier.
  string                Name              // The name of the atom.
  ParameterInfo[]       Parameters        // The list of atom parameters.
  bool                  IsCommand         // True if the atom represents an API command.
  bool                  IsDrawCall        // True if the atom represents a draw call.
  bool                  IsEndOfFrame      // True if the atom represents the end of a frame.
  string                DocumentationUrl  // The URL to the atom's documentation.
}

// ParameterInfo describes a single Atom parameter.
class ParameterInfo {
  string        Name // Name of the parameter.
  TypeInfo*     Type // Type of the parameter.
  bool          Out  // True if the parameter is an output.
}

// SimpleInfo is used for all primative types.
class SimpleInfo : TypeInfo {}