1// Copyright (C) 2022 The Android Open Source Project 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15import {EngineProxy} from '../common/engine'; 16import {TrackControllerFactory} from '../controller/track_controller'; 17import {TrackCreator} from '../frontend/track'; 18import {Selection} from './state'; 19 20export {EngineProxy} from '../common/engine'; 21export { 22 LONG, 23 LONG_NULL, 24 NUM, 25 NUM_NULL, 26 STR, 27 STR_NULL, 28} from '../common/query_result'; 29 30export interface TrackInfo { 31 // The id of this 'type' of track. This id is used to select the 32 // correct |TrackCreator| to construct the track. 33 trackKind: string; 34 35 // A human readable name for this specific track. It will normally be 36 // displayed on the left-hand-side of the track. 37 name: string; 38 39 // An opaque config for the track. 40 config: {}; 41} 42 43// Called any time a trace is loaded. Plugins should return all 44// potential tracks. Zero or more of the provided tracks may be 45// instantiated depending on the users choices. 46export type TrackProvider = (engine: EngineProxy) => Promise<TrackInfo[]>; 47 48// The public API plugins use to extend the UI. This is passed to each 49// plugin via the exposed 'activate' function. 50export interface PluginContext { 51 // DEPRECATED. In prior versions of the UI tracks were split into a 52 // 'TrackController' and a 'Track'. In more recent versions of the UI 53 // the functionality of |TrackController| has been merged into Track so 54 // |TrackController|s are not necessary in new code. 55 registerTrackController(track: TrackControllerFactory): void; 56 57 // Register a |TrackProvider|. |TrackProvider|s return |TrackInfo| for 58 // all potential tracks in a trace. The core UI selects some of these 59 // |TrackInfo|s and constructs concrete Track instances using the 60 // registered |TrackCreator|s. 61 registerTrackProvider(provider: TrackProvider): void; 62 63 // Register a track factory. The core UI invokes |TrackCreator| to 64 // construct tracks discovered by invoking |TrackProvider|s. 65 // The split between 'construction' and 'discovery' allows 66 // plugins to reuse common tracks for new data. For example: the 67 // dev.perfetto.AndroidGpu plugin could register a TrackProvider 68 // which returns GPU counter tracks. The counter track factory itself 69 // could be registered in dev.perfetto.CounterTrack - a whole 70 // different plugin. 71 registerTrack(track: TrackCreator): void; 72 73 // Register custom functionality to specify how the plugin should handle 74 // selection changes for tracks in this plugin. 75 // 76 // Params: 77 // @onDetailsPanelSelectionChange a function that takes a Selection as its 78 // parameter and performs whatever must happen on the details panel when the 79 // selection is invoked. 80 registerOnDetailsPanelSelectionChange( 81 onDetailsPanelSelectionChange: (newSelection?: Selection) => void): void; 82} 83 84export interface PluginInfo { 85 // A unique string for your plugin. To ensure the name is unique you 86 // may wish to use a URL with reversed components in the manner of 87 // Java package names. 88 pluginId: string; 89 90 // This function is called when the plugin is loaded. Generally this 91 // is called at most once shortly after the UI is loaded. However in 92 // some situations it can be called multiple times - for example 93 // when the user is toggling plugins on/off. 94 activate: (ctx: PluginContext) => void; 95} 96