service.proto

// Copyright (C) 2017 Google Inc.
//
// 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.

syntax = "proto3";

import "core/image/image.proto";
import "core/log/log_pb/log.proto";
import "core/os/device/device.proto";
import "gapis/api/service.proto";
import "gapis/service/box/box.proto";
import "gapis/service/path/path.proto";
import "gapis/service/severity/severity.proto";
import "gapis/stringtable/stringtable.proto";

package service;
option java_package = "com.google.gapid.proto.service";
option java_outer_classname = "Service";
option go_package = "github.com/google/gapid/gapis/service";

// DrawMode is an enumerator of draw modes that can be used by RenderSettings.
enum DrawMode {
  // NORMAL indicates that the draw calls should be rendered as usual
  NORMAL = 0;
  // WIREFRAME_OVERLAY indicates that the single draw call should be overlayed
  // with the wireframe of the mesh.
  WIREFRAME_OVERLAY = 1;
  // WIREFRAME_ALL indicates that all draw calls should be displayed in
  // wireframe.
  WIREFRAME_ALL = 2;
  // OVERDRAW indicates that the draw calls should render their overdraw counts
  // instead of colours.
  OVERDRAW = 3;
}

message ServerInfo {
  string name = 1;
  uint32 version_major = 2;
  uint32 version_minor = 3;
  uint32 version_point = 4;
  // A string list of features supported by the server. This feature list can be
  // used by the client to determine what new RPCs can be called.
  repeated string features = 5;
  path.Device server_local_device = 6;
}

// Messages that hold a repeated field so they can be used in oneofs.

message Commands {
  repeated path.Command list = 1;
}
message Contexts {
  repeated path.Context list = 1;
}
message Devices {
  repeated path.Device list = 1;
}
message Events {
  repeated Event list = 1;
}
message StringTableInfos {
  repeated stringtable.Info list = 1;
}
message Threads {
  repeated path.Thread list = 1;
}

message Value {
  oneof val {
    Capture capture = 1;
    CommandTree command_tree = 2;
    CommandTreeNode command_tree_node = 3;
    Commands commands = 4;
    Context context = 5;
    Contexts contexts = 6;
    ConstantSet constant_set = 7;
    Event event = 8;
    Events events = 9;
    Memory memory = 10;
    Messages messages = 11;
    path.Any path = 12;
    Report report = 13;
    Resources resources = 14;
    StateTree state_tree = 15;
    StateTreeNode state_tree_node = 16;
    Stats stats = 17;
    Thread thread = 18;
    Threads threads = 19;

    device.Instance device = 20;
    DeviceTraceConfiguration traceConfig = 21;

    api.Command command = 30;
    api.ResourceData resource_data = 31;
    api.Mesh mesh = 32;
    api.Metrics metrics = 33;
    api.MultiResourceData multi_resource_data = 34;

    image.Info image_info = 40;

    box.Value box = 50;
  }
}

message PingRequest {
}
message PingResponse {
}

message GetServerInfoRequest {
}
message GetServerInfoResponse {
  oneof res {
    ServerInfo info = 1;
    Error error = 2;
  }
}

message CheckForUpdatesRequest {
  bool include_prereleases = 1;
}
message CheckForUpdatesResponse {
  oneof res {
    Release release = 1;
    Error error = 2;
  }
}

message Release {
  string name = 1;
  uint32 version_major = 2;
  uint32 version_minor = 3;
  uint32 version_point = 4;
  bool prerelease = 5;
  string browser_url = 6;
}

message GetRequest {
  path.Any path = 1;
  // Config to use when resolving paths.
  path.ResolveConfig config = 2;
}

message GetResponse {
  oneof res {
    Value value = 1;
    Error error = 2;
  }
}

message SetRequest {
  path.Any path = 1;
  Value value = 2;
  // Config to use when resolving paths.
  path.ResolveConfig config = 3;
}

message SetResponse {
  oneof res {
    path.Any path = 1;
    Error error = 2;
  }
}

message FollowRequest {
  path.Any path = 1;
  // Config to use when resolving paths.
  path.ResolveConfig config = 2;
}

message FollowResponse {
  oneof res {
    path.Any path = 1;
    Error error = 2;
  }
}

message ProfileRequest {
  // Settings for what profile data the client wants.
  // Set all to false to flush any pending data and disable profiling.
  bool pprof = 1;  // Enable pprof profiling?
  bool trace = 2;  // Enable trace data?

  // Time in seconds between memory snapshots
  uint32 memory_snapshot_interval = 3;
}

message ProfileResponse {
  bytes pprof = 1;  // Streamed pprof data.
  bytes trace = 2;  // Streamed trace data.
  Error error = 3;
}

message GetPerformanceCountersRequest {
}
message GetPerformanceCountersResponse {
  oneof res {
    string data = 1;
    Error error = 2;
  }
}

message GetProfileRequest {
  string name = 1;
  int32 debug = 2;
}
message GetProfileResponse {
  oneof res {
    bytes data = 1;
    Error error = 2;
  }
}

message GetAvailableStringTablesRequest {
}
message GetAvailableStringTablesResponse {
  oneof res {
    StringTableInfos tables = 1;
    Error error = 2;
  }
}

message GetStringTableRequest {
  stringtable.Info table = 1;
}
message GetStringTableResponse {
  oneof res {
    stringtable.StringTable table = 1;
    Error error = 2;
  }
}

message Message {
  uint64 timestamp = 1;
  string message = 2;
}

message Messages {
  repeated Message list = 1;
}

message ImportCaptureRequest {
  string name = 1;
  bytes data = 2;
}
message ImportCaptureResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

message ExportCaptureRequest {
  path.Capture capture = 1;
}
message ExportCaptureResponse {
  oneof res {
    bytes data = 1;
    Error error = 2;
  }
}

message LoadCaptureRequest {
  string path = 1;
}
message LoadCaptureResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

message SaveCaptureRequest {
  path.Capture capture = 1;
  string path = 2;
}
message SaveCaptureResponse {
  Error error = 1;
}

message ExportReplayOptions {
  path.Report report = 1;
  repeated GetFramebufferAttachmentRequest get_framebuffer_attachment_requests =
      2;
}

message ExportReplayRequest {
  path.Capture capture = 1;
  string path = 2;
  path.Device device = 3;
  ExportReplayOptions options = 4;
}

message ExportReplayResponse {
  Error error = 1;
}

message DCECaptureRequest {
  path.Capture capture = 1;
  repeated path.Command commands = 2;
}
message DCECaptureResponse {
  oneof res {
    path.Capture capture = 1;
    Error error = 2;
  }
}

enum GraphFormat {
  PBTXT = 0;
  DOT = 1;
}

message GraphVisualizationRequest {
  path.Capture capture = 1;
  GraphFormat format = 2;
}
message GraphVisualizationResponse {
  oneof res {
    bytes graphVisualization = 1;
    Error error = 2;
  }
}

message GetDevicesRequest {
}
message GetDevicesResponse {
  oneof res {
    Devices devices = 1;
    Error error = 2;
  }
}

message GetDevicesForReplayRequest {
  path.Capture capture = 1;
}
message GetDevicesForReplayResponse {
  oneof res {
    Devices devices = 1;
    Error error = 2;
  }
}

message ReplaySettings {
  path.Device device = 1;
  bool disable_replay_optimization = 2;
  bool display_to_surface = 3;
}

message GetFramebufferAttachmentRequest {
  ReplaySettings replay_settings = 1;
  path.Command after = 2;
  api.FramebufferAttachment attachment = 3;
  RenderSettings settings = 4;
  UsageHints hints = 5;
}

message GetFramebufferAttachmentResponse {
  oneof res {
    path.ImageInfo image = 1;
    Error error = 2;
  }
}

message GetLogStreamRequest {
}

message FindRequest {
  // If true then searching will begin at from and move backwards.
  bool backwards = 1;
  // Maximum number of results to return. 0 means unlimited.
  uint32 max_items = 2;
  // The searching point.
  oneof from {
    path.CommandTreeNode command_tree_node = 5;
    path.StateTreeNode state_tree_node = 6;
  }
  // The text to search for.
  string text = 3;
  // If true then text should be treated as a regular expression.
  bool is_regex = 4;
  // If true the search should be case sensitive.
  bool is_case_sensitive = 7;
  // If true, the search will wrap.
  bool wrap = 8;
  // Config to use when resolving paths.
  path.ResolveConfig config = 9;
}

message FindResponse {
  oneof result {
    path.CommandTreeNode command_tree_node = 1;
    path.StateTreeNode state_tree_node = 2;
  }
}

enum ClientAction {
  Undefined = 0;
  Color0 = 1;
  Color1 = 2;
  Color2 = 3;
  Color3 = 4;
  Copy = 5;
  CullOn = 6;
  CullOff = 7;
  Depth = 8;
  Disable = 9;
  Edit = 10;
  Enable = 11;
  Faceted = 12;
  Flat = 13;
  Flip = 14;
  GotoReference = 15;
  HideHistogram = 16;
  Move = 17;
  Normals = 18;
  Open = 19;
  OpenRecent = 20;
  OverlayWireframe = 21;
  Points = 22;
  Save = 23;
  Search = 24;
  Select = 25;
  SelectObservation = 26;
  SelectProgram = 27;
  SelectShader = 28;
  Shaded = 29;
  Show = 30;
  ShowActivityPicker = 31;
  ShowBackground = 32;
  ShowColorChannels = 33;
  ShowEdit = 34;
  ShowError = 35;
  ShowHelp = 36;
  ShowHistogram = 37;
  ShowLogDir = 38;
  ShowReferences = 39;
  ShowTargets = 40;
  Smooth = 41;
  Triangles = 42;
  WindingCCW = 43;
  WindingCW = 44;
  Wireframe = 45;
  YUp = 46;
  ZUp = 47;
  ZoomActual = 48;
  ZoomFit = 49;
  ZoomIn = 50;
  ZoomOut = 51;
  VertexSemantics = 52;
  Overdraw = 53;
}

message ClientInteraction {
  string view = 1;
  ClientAction action = 2;
};

message ClientEventRequest {
  oneof kind {
    ClientInteraction interaction = 1;
  }
}

message ClientEventResponse {
}

message UpdateSettingsRequest {
  // Enables or disable anonymous crash reporting.
  // This will override the -crashreport command line flag.
  bool enable_crash_reporting = 1;

  // Enables or disable anonymous analytics reporting.
  // This will override the -analytics command line flag.
  bool enable_analytics = 2;

  // The client identifier to use for analytics reporting.
  // This will override the -analytics command line flag.
  string client_id = 3;

  // The path to the adb executable to use.
  // This will override the -adb command line flag.
  string adb = 4;
}

message UpdateSettingsResponse {
  Error error = 1;
}

// Gapid is the RPC service to the GAPIS server.
service Gapid {
  // Ping is a no-op function that returns immediately.
  // It can be used to measure connection latency or to keep the
  // process alive if started with the "idle-timeout" command line flag.
  rpc Ping(PingRequest) returns (PingResponse) {
  }

  // GetServerInfo returns information about the running server.
  rpc GetServerInfo(GetServerInfoRequest) returns (GetServerInfoResponse) {
  }

  // CheckForUpdates checks for a new build of GAPID on the hosting server.
  // Care should be taken to call this infrequently to avoid reaching the
  // server's maximum unauthenticated request limits.
  rpc CheckForUpdates(CheckForUpdatesRequest)
      returns (CheckForUpdatesResponse) {
  }

  // Get resolves and returns the object, value or memory at the path p.
  rpc Get(GetRequest) returns (GetResponse) {
  }

  // Set creates a copy of the capture referenced by p, but with the object,
  // value or memory at p replaced with v. The path returned is identical to p,
  // but with the base changed to refer to the new capture.
  rpc Set(SetRequest) returns (SetResponse) {
  }

  // Follow returns the path to the object that the value at p links to.
  // If the value at p does not link to anything then nil is returned.
  rpc Follow(FollowRequest) returns (FollowResponse) {
  }

  // GetAvailableStringTables returns list of available string table
  // descriptions.
  rpc GetAvailableStringTables(GetAvailableStringTablesRequest)
      returns (GetAvailableStringTablesResponse) {
  }

  // GetStringTable returns the requested string table.
  rpc GetStringTable(GetStringTableRequest) returns (GetStringTableResponse) {
  }

  // Import imports capture data emitted by the graphics spy, returning the new
  // capture identifier.
  rpc ImportCapture(ImportCaptureRequest) returns (ImportCaptureResponse) {
  }

  // ExportCapture returns a capture's data that can be consumed by
  // ImportCapture or LoadCapture.
  rpc ExportCapture(ExportCaptureRequest) returns (ExportCaptureResponse) {
  }

  // LoadCapture imports capture data from a local file, returning the new
  // capture identifier.
  rpc LoadCapture(LoadCaptureRequest) returns (LoadCaptureResponse) {
  }

  // SaveCapture saves capture to a file.
  rpc SaveCapture(SaveCaptureRequest) returns (SaveCaptureResponse) {
  }

  // ExportReplay saves replay commands and assets to file.
  rpc ExportReplay(ExportReplayRequest) returns (ExportReplayResponse) {
  }

  // DCECapture returns a new capture containing only the requested commands
  // and their dependencies.
  rpc DCECapture(DCECaptureRequest) returns (DCECaptureResponse) {
  }

  rpc GetGraphVisualization(GraphVisualizationRequest)
      returns (GraphVisualizationResponse) {
  }
  // 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.
  // The primary device (usually host) will be first.
  rpc GetDevices(GetDevicesRequest) returns (GetDevicesResponse) {
  }

  // GetDevicesForReplay returns the list of replay devices avaliable to the
  // server that are capable of replaying the given capture.
  // These include local replay devices and any connected Android devices.
  // This list may change over time, as devices are connected and disconnected.
  // If both connected Android and Local replay devices are found,
  // the local Android devices will be returned first.
  rpc GetDevicesForReplay(GetDevicesForReplayRequest)
      returns (GetDevicesForReplayResponse) {
  }

  // GetFramebufferAttachment returns the ImageInfo identifier describing the
  // given framebuffer attachment and device, immediately following the command
  // after.
  // The provided RenderSettings structure can be used to adjust maximum desired
  // dimensions of the image, as well as applying debug visualizations.
  rpc GetFramebufferAttachment(GetFramebufferAttachmentRequest)
      returns (GetFramebufferAttachmentResponse) {
  }

  // GetLogStream calls the handler with each log record raised until the
  // context is cancelled.
  rpc GetLogStream(GetLogStreamRequest) returns (stream log.Message) {
  }

  // Find searches for data, streaming the results.
  rpc Find(FindRequest) returns (stream FindResponse) {
  }

  // ClientEvent records a client event action, used for analytics.
  // If the user has not opted-in for analytics then this call does nothing.
  rpc ClientEvent(ClientEventRequest) returns (ClientEventResponse) {
  }

  // FindTraceTargets returns trace targets matching the given search
  // parameters.
  rpc FindTraceTargets(FindTraceTargetsRequest)
      returns (FindTraceTargetsResponse) {
  }

  // TraceTargetTreeNode returns information about the trace target
  rpc TraceTargetTreeNode(TraceTargetTreeNodeRequest)
      returns (TraceTargetTreeNodeResponse) {
  }

  // Trace returns a steam that can be used to start and stop
  // a trace
  rpc Trace(stream TraceRequest) returns (stream TraceResponse) {
  }

  // Updates environment settings.
  rpc UpdateSettings(UpdateSettingsRequest) returns (UpdateSettingsResponse) {
  }

  ///////////////////////////////////////////////////////////////
  // Below are debugging APIs which may be removed in the future.
  ///////////////////////////////////////////////////////////////

  // Profile starts self-profiling the server.
  rpc Profile(stream ProfileRequest) returns (stream ProfileResponse) {
  }

  // GetPerformanceCounters returns the values of all global counters as
  // a JSON blob.
  rpc GetPerformanceCounters(GetPerformanceCountersRequest)
      returns (GetPerformanceCountersResponse) {
  }

  // GetProfile returns the pprof profile with the given name.
  rpc GetProfile(GetProfileRequest) returns (GetProfileResponse) {
  }

  // GetTimestamps returns the timestamps of the begin and end of execution of a
  // command buffer.
  rpc GetTimestamps(GetTimestampsRequest) returns (GetTimestampsResponse) {
  }
}

message Error {
  oneof err {
    ErrInternal err_internal = 1;
    ErrDataUnavailable err_data_unavailable = 2;
    ErrInvalidPath err_invalid_path = 3;
    ErrInvalidArgument err_invalid_argument = 4;
    ErrPathNotFollowable err_path_not_followable = 5;
    ErrUnsupportedVersion err_unsupported_version = 6;
  }
}

// ErrInternal is the error raised when an internal server error has occurred.
message ErrInternal {
  string message = 1;
}

// ErrDataUnavailable is the error raised when the requested data is
// unavailable. For instance: the error raised when a framebuffer is
// requested at a point in the capture where none is bound.
message ErrDataUnavailable {
  // The reason the data is unavailable.
  stringtable.Msg reason = 1;
  // If true, then making the same request at a later time may result in data.
  bool transient = 2;
}

// ErrInvalidPath is the error raised when the specified path is invalid.
// This type of error is permanent.
message ErrInvalidPath {
  // The description of what's invalid.
  stringtable.Msg reason = 1;
  // The part of the path that was invalid.
  path.Any path = 2;
}

// ErrInvalidArgument is the error raised when one of the parameters to an RPC
// call is invalid.
// This type of error is permanent.
message ErrInvalidArgument {
  // The description of what's invalid.
  stringtable.Msg reason = 1;
}

// ErrPathNotFollowable is the error raised when attempting to follow a path
// that cannot be followed.
message ErrPathNotFollowable {
  path.Any path = 1;
}

// ErrUnsupportedVersion is the error raised attempting to load data with an
// unsupported version.
message ErrUnsupportedVersion {
  // The reason the data is unsupported.
  stringtable.Msg reason = 1;
  // If true, the client should prompt the user to update GAPID.
  bool suggest_update = 2;
}

// Capture describes single capture file held by the server.
message Capture {
  // Name given to the capture. e.g. "KittyWorld"
  string name = 1;
  // Information about the device used to create the capture.
  device.Instance device = 2;
  // Information about the abi used by the traced process.
  device.ABI ABI = 3;
  // Number of commands in this capture.
  uint64 num_commands = 4;
  // List of graphics APIs used by this capture.
  repeated path.API APIs = 5;
  // List of all the memory observations made by the application.
  repeated MemoryRange observations = 6;
}

// Report describes all warnings and errors found by a capture.
message Report {
  // Report items for this report.
  repeated ReportItem items = 1;
  // Report groups for this report.
  repeated ReportGroup groups = 2;
  // Array of strings for messages.
  repeated string strings = 3;
  // Array of values for messages.
  repeated stringtable.Value values = 4;
}

// ReportItem represents an entry in a report.
message ReportItem {
  // The severity of the report item.
  severity.Severity severity = 1;
  // The message for the item.
  MsgRef message = 2;
  // The path to the command that reported the issue.
  path.Command command = 3;
  // The references to tags associated with this item.
  repeated MsgRef tags = 4;
}

// Stats stores the statistics for a capture
message Stats {
  // The draw calls per frame, if requested in the path.Stats.
  repeated uint64 draw_calls = 1;
  uint64 trace_start = 2;
}

// Thread represents a single thread in the capture.
message Thread {
  string name = 1;
}

// MsgRef references a message in a Report.
message MsgRef {
  // The index in Report.strings of the message identifier.
  uint32 identifier = 1;
  // The indexed arguments.
  repeated MsgRefArgument arguments = 2;
}

// MsgRefArgument is an argument formed from two indices into the report.
message MsgRefArgument {
  // The index in Report.strings of the argument identifier.
  uint32 key = 1;
  // The index in Report.values of the argument value.
  uint32 value = 2;
}

// ReportGroup represents a group of ReportItem which have the same tag.
message ReportGroup {
  // The reference to Msg which describes this group.
  MsgRef name = 1;
  // The indices of report items which belong to this group.
  repeated uint32 items = 2;
  // The union of all Items tags. Currently isn't supported and is nil. TODO:
  // Add filtering support for the entire group.
  repeated MsgRef tags = 3;
}

// Memory describes the state of a range of memory at a specific point in
// the command stream.
message Memory {
  // The memory values for the span.
  bytes data = 1;
  // The data-relative ranges that were read-from at the specified command.
  repeated MemoryRange reads = 2;
  // The data-relative ranges that were written-to at the specified command.
  repeated MemoryRange writes = 3;
  // The data-relative ranges that have been observed.
  repeated MemoryRange observed = 4;
}

// MemoryRange represents a contiguous range of memory.
message MemoryRange {
  // The address of the first byte in the memory range.
  uint64 base = 1;
  // The number of bytes that are in the memory range.
  uint64 size = 2;
}

// UsageHints hints to the server the intended usage of the result of a request.
// This can be used to improve performance and responsiveness of the RPCs.
message UsageHints {
  // Preview indicates that the request has been made for a thumbnail or
  // low-quality representation of the underlying data. Previews are considered
  // non-critical and non-urgent; the server may consider scheduling other work
  // ahead of previews, and possibly delay the processing of the request to
  // batch together requests.
  bool preview = 1;

  // Primary indicates that the request has been made for the primary view.
  // Primary requests are prioritized and are low-latency.
  bool primary = 2;

  // Background indicates that this request is non-critical, non-urgent and
  // should process in the background. All other non-background processes should
  // be considered more urgent. Background requests may be interrupted for
  // non-background requests.
  bool background = 3;
}

// RenderSettings contains settings and flags to be used in replaying and
// returning a bound render target's color buffer.
message RenderSettings {
  // The desired maximum width of the image. The returned image may be larger
  // than this.
  uint32 max_width = 1;
  // The desired minimum height of the image. The returned image may be larger
  // than this.
  uint32 max_height = 2;
  // The draw mode to use when rendering.
  DrawMode draw_mode = 3;
}

// Resources contains the full list of resources used by a capture.
message Resources {
  repeated ResourcesByType types = 1;
}

// ResourcesByType contains all resources of a specific type.
message ResourcesByType {
  api.ResourceType type = 1;
  repeated Resource resources = 2;
}

// Resource describes a single resource.
message Resource {
  // The resource's unique identifier.
  path.ID ID = 1;
  // The context that created this resource.
  path.Context context = 8;
  // The resource identifier used for display.
  string handle = 2;
  // The resource label.
  string label = 3;
  // An int used to sort the resources for presentation.
  uint64 order = 4;
  // The list of command indices where the resource was used.
  repeated path.Command accesses = 5;
  // The command at which this resource was deleted/destroyed.
  path.Command deleted = 6;
  // The command at which this resource was created.
  path.Command created = 7;
}

// Context represents a single rendering context in the capture.
message Context {
  // The context name.
  string name = 1;
  // The API that this context belongs to.
  path.API API = 2;
  // The estimated importance for the context. 0 = lowest priority.
  uint32 priority = 3;
}

// CommandTree represents a command tree hierarchy.
message CommandTree {
  path.CommandTreeNode root = 1;
}

// CommandTreeNode is a node in a command tree hierarchy.
message CommandTreeNode {
  // The path to the command that best represents this group. For example the
  // the last draw call in a frame.
  path.Command representation = 1;
  // Number of child nodes.
  uint64 num_children = 2;
  // Group name if this node represents a group of commands.
  string group = 3;
  // Path to the command range represented by this node.
  path.Commands commands = 4;
  // Number of commands encapsulated by this group.
  uint64 num_commands = 5;
}

// ConstantSet is a collection on name-value pairs to be used as an enumeration
// of possible values for a field or parameter.
message ConstantSet {
  repeated Constant constants = 1;
  bool is_bitfield = 2;
}

// Constant is a name-value pair that is owned by a ConstantSet.
message Constant {
  // The name of the constant.
  string name = 1;
  // The value of the constant.
  uint64 value = 2;
}

// Event represents a single event in the capture.
message Event {
  EventKind kind = 1;
  path.Command command = 2;
  uint64 timestamp = 3;
}

enum EventKind {
  Unknown = 0;
  DrawCall = 1;
  TransformFeedback = 2;
  // All command events should occur between FirstInFrame and LastInFrame
  // (except FramebufferObservation, which comes last as gapit sxs_video
  // depends on this).
  FirstInFrame = 3;
  LastInFrame = 4;
  Clear = 5;
  UserMarker = 6;
  PushUserMarker = 7;
  PopUserMarker = 8;
  FramebufferObservation = 9;
  // Note you probably only want to use AllCommands for debugging/testing
  // purposes.
  AllCommands = 10;
}

// StateTree represents a state tree hierarchy.
message StateTree {
  path.StateTreeNode root = 1;
}

// StateTreeNode is a node in a state tree hierarchy.
message StateTreeNode {
  // Number of child nodes.
  uint64 num_children = 1;
  // The name of the field or group.
  string name = 2;
  // The path to the value.
  path.Any value_path = 3;
  // The 'preview' value of the field.
  // For simple POD types, this may be the actual value, in which case
  // preview_is_value will be true.
  // For more complex types, this may be a string representation of the value.
  // Long arrays may be truncated.
  box.Value preview = 4;
  // If true then preview is the complete data of the node. In this situation
  // preview is equal to calling Get() on the path.
  bool preview_is_value = 5;
  // The possible alternative named values for the field.
  path.ConstantSet constants = 6;
}

message TraceTargetTreeNode {
  // The name of the node
  string name = 1;
  // The icon of this node.
  bytes icon = 2;
  // The uri of this node
  string uri = 3;
  // The parent of this node. It will point to
  // this node if there is no parent
  string parent_uri = 4;
  // Child nodes from this tree node
  repeated string children_uris = 5;
  // The uri that should be passed to the TraceOptions to trace this target.
  // If null, this node is not traceable.
  string trace_uri = 6;
  // The friendly application name, if it makes sense.
  string friendly_application = 7;
  // The friendly executable name, if it makes sense.
  string friendly_executable = 8;
}

message TraceTargetTreeNodes {
  repeated TraceTargetTreeNode nodes = 1;
}

message TraceTargetTreeNodeRequest {
  path.Device device = 1;
  string uri = 2;
  float density = 3;
}

message TraceTargetTreeNodeResponse {
  oneof val {
    TraceTargetTreeNode node = 1;
    Error error = 2;
  }
}

message FindTraceTargetsRequest {
  path.Device device = 1;
  string uri = 2;
}

message FindTraceTargetsResponse {
  oneof val {
    TraceTargetTreeNodes nodes = 1;
    Error error = 2;
  }
}

message TraceOptions {
  // The device on which to trace
  path.Device device = 1;
  oneof app {
    // The device-specific uri to trace
    string uri = 2;
    // The application to upload and trace
    bytes upload_application = 3;
    // The server port that should be connected to for tracing
    uint32 port = 4;
  }
  // What APIs should we trace
  repeated string apis = 5;
  // Any additional command-line args to pass to the app
  string additional_command_line_args = 6;
  // What directory should be used for tracing
  string cwd = 7;
  // Additional environment variables to add in the form 'X=Y'
  repeated string environment = 8;
  // How long should we trace for
  float duration = 9;
  // What frames should we insert into the trace
  uint32 observe_frame_frequency = 10;
  // What draw calls should we insert into the trace
  uint32 observe_draw_frequency = 11;
  // What frame should we start tracing.
  uint32 start_frame = 12;
  // How many frames should we capture
  uint32 frames_to_capture = 13;
  // Disable disable pre-compiled shaders.
  bool disable_pcs = 14;
  // Insert extra commands to record error state
  bool record_error_state = 15;
  // Wait for an event to start tracing
  bool defer_start = 16;
  // Disable buffering. (In case of a crash)
  bool no_buffer = 17;
  // Clear the application cache
  bool clear_cache = 18;
  // Hide unknown extensions
  bool hide_unknown_extensions = 19;
  // Record trace timing
  bool record_trace_times = 20;
  // Where should we save the capture file.
  string server_local_save_path = 21;
  // Name of the pipe to connect/listen to.
  string pipe_name = 22;
}

enum TraceEvent {
  Begin = 0;   // Begin tracing (only valid if started with MidExecution)
  Stop = 1;    // Flush and stop the trace
  Status = 2;  // Get the status of the trace
}

message TraceRequest {
  oneof action {
    TraceOptions initialize = 1;
    TraceEvent query_event = 2;
  }
}

enum TraceStatus {
  Uninitialized = 0;
  Initializing = 1;
  Capturing = 2;
  WaitingToStart = 3;
  Done = 4;
}

message StatusResponse {
  int64 bytes_captured = 1;  // How many bytes have been captured so far
  TraceStatus status = 2;    // What state the trace is in
}

message TraceResponse {
  oneof res {
    StatusResponse status = 1;
    Error error = 2;
  }
}

message DeviceTraceConfiguration {
  // Is the path to the app on this device server-local.
  bool server_local_path = 1;
  // Does it make sense to specify a CWD for the application.
  bool can_specify_cwd = 2;
  // Can we upload an application to trace.
  bool can_upload_application = 3;
  // Can we specify an environment
  bool can_specify_env = 4;
  // The default URI that should be used for looking at packages
  string preferred_root_uri = 5;
  // API-specific trace information
  repeated DeviceAPITraceConfiguration apis = 6;
  // Is there a cache that can be cleared.
  bool has_cache = 7;
}

enum FeatureStatus {
  NotSupported = 0;
  Supported = 1;
  Experimental = 2;
}

message DeviceAPITraceConfiguration {
  // What is the API this is for.
  string api = 1;
  // Does this API support disabling pre-compiled shaders.
  bool can_disable_pcs = 2;
  // Does this API support MEC.
  FeatureStatus mid_execution_capture_support = 3;
}

// GetTimestampsRequest is the request send to server to get the timestamps for
// the commands in the capture.
message GetTimestampsRequest {
  path.Capture capture = 1;
  path.Device device = 2;
}

// Timestamps describes the durations of commands execution, each of which
// is specified in a TimestampsItem message.
message Timestamps {
  repeated TimestampsItem timestamps = 1;
}

// TimestampsItem represents one entry in a Timestamps report.
// It describes the duratoin of execution time between the two commands
// specified by "begin" and "end" fields.
message TimestampsItem {
  // The path of the command which begins the time measurement.
  path.Command begin = 1;
  // The path of the command which ends the time measurement.
  path.Command end = 2;
  // The duration in nanoseconds between the two commands specified.
  uint64 time_in_nanoseconds = 3;
}

// GetTimestampsResponse is the response message server sends back which
// contains the time duratoins for the commands when replay the trace.
message GetTimestampsResponse {
  oneof res {
    Timestamps timestamps = 1;
    Error error = 2;
  }
}