source/ps/ProfileViewer.h

   1 /* Copyright (C) 2009 Wildfire Games.
   2  * This file is part of 0 A.D.
   3  *
   4  * 0 A.D. is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * 0 A.D. is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Viewing profiling information (timing and other statistics)
  20  */
  21
  22 #ifndef INCLUDED_PROFILE_VIEWER
  23 #define INCLUDED_PROFILE_VIEWER
  24
  25 #include "lib/input.h"
  26 #include "ps/CStr.h"
  27 #include "ps/Singleton.h"
  28
  29 class ScriptInterface;
  30
  31 namespace JS
  32 {
  33         class Value;
  34 }
  35
  36 /**
  37  * Struct ProfileColumn: Describes one column of an AbstractProfileTable.
  38  */
  39 struct ProfileColumn
  40 {
  41         /// Title of the column
  42         CStr title;
  43
  44         /// Recommended width of the column, in pixels.
  45         size_t width;
  46
  47         ProfileColumn(const CStr& t, size_t w) : title(t), width(w) { }
  48 };
  49
  50
  51 /**
  52  * Class AbstractProfileTable: Profile table data model.
  53  *
  54  * Clients that wish to display debug information in the profile viewer
  55  * have to implement this class and hook it into CProfileViewer.
  56  *
  57  * Note that the profiling system is robust against deletion of
  58  * object instances in the sense that it will automatically remove
  59  * an AbstractProfileTable instance from its internal records when
  60  * you delete it.
  61  * Conversely, deleting an AbstractProfileTable instance is the responsibility
  62  * of its creator.
  63  */
  64 class AbstractProfileTable
  65 {
  66 public:
  67         virtual ~AbstractProfileTable();
  68
  69         /**
  70          * GetName: Short descriptive name of this table (should be static).
  71          *
  72          * @return Descriptive name of this table.
  73          */
  74         virtual CStr GetName() = 0;
  75
  76         /**
  77          * GetTitle: Longer, explanatory text (can be dynamic).
  78          *
  79          * @return Title for the table.
  80          */
  81         virtual CStr GetTitle() = 0;
  82
  83
  84         /**
  85          * GetNumberRows
  86          *
  87          * @return Number of rows in this table.
  88          */
  89         virtual size_t GetNumberRows() = 0;
  90
  91         /**
  92          * GetColumnDescriptions
  93          *
  94          * @return A vector describing all columns of the table.
  95          */
  96         virtual const std::vector<ProfileColumn>& GetColumns() = 0;
  97
  98         /**
  99          * GetCellText
 100          *
 101          * @param row Row index (the first row has index 0).
 102          * @param col Column index (the first column has index 0).
 103          *
 104          * @return Text to be displayed in the given cell.
 105          */
 106         virtual CStr GetCellText(size_t row, size_t col) = 0;
 107
 108         /**
 109          * GetChild: Return a row's child table if the child is expandable.
 110          *
 111          * @param row Row index (the first row has index 0).
 112          *
 113          * @return Pointer to the child table if the given row has one.
 114          * Otherwise, return 0.
 115          */
 116         virtual AbstractProfileTable* GetChild(size_t row) = 0;
 117
 118         /**
 119          * IsHighlightRow
 120          *
 121          * @param row Row index (the first row has index 0).
 122          *
 123          * @return true if the row should be highlighted in a special color.
 124          */
 125         virtual bool IsHighlightRow(size_t row) { UNUSED2(row); return false; }
 126 };
 127
 128
 129 struct CProfileViewerInternals;
 130
 131 /**
 132  * Class CProfileViewer: Manage and display profiling tables.
 133  */
 134 class CProfileViewer : public Singleton<CProfileViewer>
 135 {
 136         friend class AbstractProfileTable;
 137
 138 public:
 139         CProfileViewer();
 140         ~CProfileViewer();
 141
 142         /**
 143          * RenderProfile: Render the profile display using OpenGL if the user
 144          * has enabled it.
 145          */
 146         void RenderProfile();
 147
 148         /**
 149          * Input: Filter and handle any input events that the profile display
 150          * is interested in.
 151          *
 152          * In particular, this function handles enable/disable of the profile
 153          * display as well as navigating the information tree.
 154          *
 155          * @param ev The incoming event.
 156          *
 157          * @return IN_PASS or IN_HANDLED depending on whether the event relates
 158          * to the profiling display.
 159          */
 160         InReaction Input(const SDL_Event_* ev);
 161
 162         /**
 163          * AddRootTable: Add a new profile table as a root table (i.e. the
 164          * tables that you cycle through via the profile hotkey).
 165          *
 166          * @note Tables added via this function are automatically removed from
 167          * the list of root tables when they are deleted.
 168          *
 169          * @param table This table is added as a root table.
 170          * @param front If true then the table will be the new first in the list,
 171          * else it will be the last.
 172          */
 173         void AddRootTable(AbstractProfileTable* table, bool front = false);
 174
 175         /**
 176          * InputThunk: Delegate to the singleton's Input() member function
 177          * if the singleton has been initialized.
 178          *
 179          * This allows our input handler to be installed via in_add_handler
 180          * like a normal, global function input handler.
 181          */
 182         static InReaction InputThunk(const SDL_Event_* ev);
 183
 184         /**
 185          * SaveToFile: Save the current profiler data (for all profile tables)
 186          * to a file in the 'logs' directory.
 187          */
 188         void SaveToFile();
 189
 190         /**
 191          * SaveToJS: Return a script value containing the current profiler data
 192          * (for all profile tables).
 193          */
 194         JS::Value SaveToJS(ScriptInterface& scriptInterface);
 195
 196         /**
 197          * ShowTable: Set the named profile table to be the displayed one. If it
 198          * is not found, no profile is displayed.
 199          *
 200          * @param table The table name (matching AbstractProfileTable::GetName),
 201          * or the empty string to display no table.
 202          */
 203         void ShowTable(const CStr& table);
 204
 205 private:
 206         CProfileViewerInternals* m;
 207 };
 208
 209 #define g_ProfileViewer CProfileViewer::GetSingleton()
 210
 211 #endif