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/gfxapi/gfxapi.proto";
import "gapis/service/box/box.proto";
import "gapis/service/path/path.proto";
import "gapis/stringtable/stringtable.proto";

package service;
option java_package = "com.google.gapid.proto.service";
option java_outer_classname = "Service";

// WireframeMode is an enumerator of wireframe modes that can be used by
// RenderSettings.
enum WireframeMode {
  // None indicates that nothing should be drawn in wireframe.
  None = 0;
  // Overlay indicates that the single draw call should be overlayed
  // with the wireframe of the mesh.
  Overlay = 1;
  // All indicates that all draw calls should be displayed in wireframe.
  All = 2;
}

// Severity defines the severity of a logging message.
// The values must be identical to values in core/log/severity.go
enum Severity {
	// Verbose indicates extremely verbose level messages.
	VerboseLevel = 0;
	// Debug indicates debug-level messages.
	DebugLevel = 1;
	// Info indicates minor informational messages that should generally be ignored.
	InfoLevel = 2;
	// Warning indicates issues that might affect performance or compatibility, but could be ignored.
	WarningLevel = 3;
	// Error indicates non terminal failure conditions that may have an effect on results.
	ErrorLevel = 4;
	// Fatal indicates a fatal error and the process should be terminated.
	FatalLevel = 5;
}

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;
}

// 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;
    Command command = 2;
    CommandTree command_tree = 3;
    CommandTreeNode command_tree_node = 4;
    Commands commands = 5;
    Context context = 6;
    Contexts contexts = 7;
    ConstantSet constant_set = 8;
    Event event = 9;
    Events events = 10;
    Memory memory = 11;
    path.Any path = 12;
    Report report = 13;
    Resources resources = 14;
    StateTree state_tree = 15;
    StateTreeNode state_tree_node = 16;
    Thread thread = 17;
    Threads threads = 18;

    device.Instance device = 20;

    gfxapi.ResourceData resource_data = 30;
    gfxapi.Mesh mesh = 31;

    image.Info2D image_info_2d = 40;

    box.Value box = 50;
  }
}

message PingRequest {}
message PingResponse {}

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

message GetRequest {
  path.Any path = 1;
}

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

message SetRequest {
  path.Any path = 1;
  Value value = 2;
}

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

message FollowRequest {
  path.Any path = 1;
}

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

message BeginCPUProfileRequest {}
message BeginCPUProfileResponse {
  Error error = 1;
}

message EndCPUProfileRequest {}
message EndCPUProfileResponse {
  oneof res {
    bytes data = 1;
    Error error = 2;
  }
}

message GetPerformanceCountersRequest {}
message GetPerformanceCountersResponse {
  oneof res {
    bytes 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 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 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 GetFramebufferAttachmentRequest {
  path.Device device = 1;
  path.Command after = 2;
  gfxapi.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;
}

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

// 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) {}

  // 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) {}

  // 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.
  // If both connected Android and Local replay devices are found,
  // the local Android devices will be returned 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 atom
  // 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_pb.Message) {}

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

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

  // BeginCPUProfile starts CPU self-profiling of the server.
  // If the CPU is already being profiled then this function will return an
  // error.
  rpc BeginCPUProfile(BeginCPUProfileRequest) returns (BeginCPUProfileResponse) {}

  // EndCPUProfile ends the CPU profile, returning the pprof samples.
  rpc EndCPUProfile(EndCPUProfileRequest) returns (EndCPUProfileResponse) {}

  // 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) {}
}

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;
  }
}

// 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;
}

// 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 = 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;
}

// 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;
}

// 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 wireframe mode to use when rendering.
  WireframeMode wireframe_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 {
  gfxapi.ResourceType type = 1;
  repeated Resource resources = 2;
}

// Resource describes a single resource.
message Resource {
  // The resource's unique identifier.
  path.ID id = 1;
  // 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;
}

// 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;
}

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

// CommandTreeNode is a node in a command tree hierarchy.
message CommandTreeNode {
  // Number of child nodes.
  uint64 num_children = 1;
  // Group name if this node represents a group of commands.
  string group = 2;
  // Path to the command range represented by this node.
  path.Commands commands = 3;
  // Number of commands encapsulated by this group.
  uint64 num_commands = 4;
}

// Command describes a single intercepted command or sub-command.
message Command {
  // The function name.
  string name = 1;
  // The function's API.
  path.API api = 2;
  // The list of function parameters.
  repeated Parameter parameters = 3;
  // The function return value 'parameter'.
  Parameter result = 4;
  // The thread associated with this comand. May be nil.
  path.Thread thread = 5;
  // The context associated with this comand. May be nil.
  path.Context context = 6;
}

// Parameter is a parameter of a command.
message Parameter {
  // The name of the parameter.
  string name = 1;
  // The value of the parameter.
  box.Value value = 2;
  // The possible alternative named values for the parameter.
  path.ConstantSet constants = 3;
}

// 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;
}

enum EventKind {
    Unknown = 0;
    DrawCall = 1;
    FirstInFrame = 2;
    LastInFrame = 3;
    Clear = 4;
    UserMarker = 5;
    PushUserMarker = 6;
    PopUserMarker = 7;
    FramebufferObservation = 8;
}

// 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;
}