1 /*!*********************************************************************** 2 3 @file PVRScopeComms.h 4 @copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved. 5 @brief PVRScopeComms header file. @copybrief ScopeComms 6 7 **************************************************************************/ 8 9 #ifndef _PVRSCOPE_H_ 10 #define _PVRSCOPE_H_ 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /* 17 SGSPerfServer and PVRTune communications 18 */ 19 20 /*! 21 @addtogroup ScopeComms PVRScopeComms 22 @brief The PVRScopeComms functionality of PVRScope allows an application to send user defined information to 23 PVRTune via PVRPerfServer, both as counters and marks, or as editable data that can be 24 passed back to the application. 25 @details PVRScopeComms has the following limitations: 26 \li PVRPerfServer must be running on the host device if a @ref ScopeComms enabled 27 application wishes to send custom counters or marks to PVRTune. If the application in 28 question also wishes to communicate with PVRScopeServices without experiencing any 29 undesired behaviour PVRPerfServer should be run with the '--disable-hwperf' flag. 30 \li The following types may be sent: Boolean, Enumerator, Float, Integer, String. 31 @{ 32 */ 33 34 /**************************************************************************** 35 ** Enums 36 ****************************************************************************/ 37 38 /*!************************************************************************** 39 @enum ESPSCommsLibType 40 @brief Each editable library item has a data type associated with it 41 ****************************************************************************/ 42 /// 43 enum ESPSCommsLibType 44 { 45 eSPSCommsLibTypeString, ///< data is string (NOT NULL-terminated, use length parameter) 46 eSPSCommsLibTypeFloat, ///< data is SSPSCommsLibraryTypeFloat 47 eSPSCommsLibTypeInt, ///< data is SSPSCommsLibraryTypeInt 48 eSPSCommsLibTypeEnum, ///< data is string (NOT NULL-terminated, use length parameter). First line is selection number, subsequent lines are available options. 49 eSPSCommsLibTypeBool ///< data is SSPSCommsLibraryTypeBool 50 }; 51 52 /**************************************************************************** 53 ** Structures 54 ****************************************************************************/ 55 56 // Internal implementation data 57 struct SSPSCommsData; 58 59 /*!************************************************************************** 60 @struct SSPSCommsLibraryItem 61 @brief Definition of one editable library item 62 ****************************************************************************/ 63 struct SSPSCommsLibraryItem 64 { 65 66 const char *pszName; ///< Item name. If dots are used, PVRTune could show these as a foldable tree view. 67 unsigned int nNameLength; ///< Item name length 68 69 ESPSCommsLibType eType; ///< Item type 70 71 const char *pData; ///< Item data 72 unsigned int nDataLength; ///< Item data length 73 }; 74 75 /*!************************************************************************** 76 @struct SSPSCommsLibraryTypeFloat 77 @brief Current, minimum and maximum values for an editable library item of type float 78 ****************************************************************************/ 79 struct SSPSCommsLibraryTypeFloat 80 { 81 float fCurrent; ///< Current value 82 float fMin; ///< Minimal value 83 float fMax; ///< Maximum value 84 }; 85 86 /*!************************************************************************** 87 @struct SSPSCommsLibraryTypeInt 88 @brief Current, minimum and maximum values for an editable library item of type int 89 ****************************************************************************/ 90 struct SSPSCommsLibraryTypeInt 91 { 92 int nCurrent; ///< Current value 93 int nMin; ///< Minimal value 94 int nMax; ///< Maximum value 95 }; 96 97 /*!************************************************************************** 98 @struct SSPSCommsLibraryTypeBool 99 @brief Current value for an editable library item of type bool 100 ****************************************************************************/ 101 struct SSPSCommsLibraryTypeBool 102 { 103 bool bValue; ///< Boolean value 104 }; 105 106 /*!************************************************************************** 107 @struct SSPSCommsCounterDef 108 @brief Definition of one custom counter 109 ****************************************************************************/ 110 struct SSPSCommsCounterDef 111 { 112 const char *pszName; ///< Custom counter name 113 unsigned int nNameLength; ///< Custom counter name length 114 }; 115 116 /**************************************************************************** 117 ** Declarations 118 ****************************************************************************/ 119 120 121 /*!************************************************************************** 122 @brief Initialise @ref ScopeComms 123 @return @ref ScopeComms data. 124 ****************************************************************************/ 125 SSPSCommsData *pplInitialise( 126 const char * const pszName, ///< String to describe the application 127 const unsigned int nNameLen ///< String length 128 ); 129 130 /*!************************************************************************** 131 @brief Shutdown or de-initialise the remote control section of PVRScope. 132 ****************************************************************************/ 133 void pplShutdown( 134 SSPSCommsData *psData ///< Context data 135 ); 136 137 /*!************************************************************************** 138 @brief Query for the time. Units are microseconds, resolution is undefined. 139 ****************************************************************************/ 140 unsigned int pplGetTimeUS( 141 SSPSCommsData &sData ///< Context data 142 ); 143 144 /*!************************************************************************** 145 @brief Send a time-stamped string marker to be displayed in PVRTune. 146 @details Examples might be: 147 \li switching to outdoor renderer 148 \li starting benchmark test N 149 ****************************************************************************/ 150 bool pplSendMark( 151 SSPSCommsData &sData, ///< Context data 152 const char * const pszString, ///< Time-stamped string 153 const unsigned int nLen ///< String length 154 ); 155 156 /*!************************************************************************** 157 @brief Send a time-stamped begin marker to PVRTune. 158 @details Every begin must be followed by an end; they cannot be interleaved or 159 nested. PVRTune will show these as an activity timeline. 160 ****************************************************************************/ 161 bool pplSendProcessingBegin( 162 SSPSCommsData &sData, ///< Context data 163 const char * const pszString, ///< Name of the processing block 164 const unsigned int nLen, ///< String length 165 const unsigned int nFrame=0 ///< Iteration (or frame) number, by which processes can be grouped. 166 ); 167 168 /*!************************************************************************** 169 @brief Send a time-stamped end marker to PVRTune. 170 @details Every end must be preceeded by a begin; they cannot be interleaved or 171 nested. PVRTune will show these as an activity timeline. 172 ****************************************************************************/ 173 bool pplSendProcessingEnd( 174 SSPSCommsData &sData ///< Context data 175 ); 176 177 /*!************************************************************************** 178 @brief Create a library of remotely editable items 179 ****************************************************************************/ 180 bool pplLibraryCreate( 181 SSPSCommsData &sData, ///< Context data 182 const SSPSCommsLibraryItem * const pItems, ///< Editable items 183 const unsigned int nItemCount ///< Number of items 184 ); 185 186 /*!************************************************************************** 187 @brief Query to see whether a library item has been edited, and also retrieve the new data. 188 ****************************************************************************/ 189 bool pplLibraryDirtyGetFirst( 190 SSPSCommsData &sData, ///< Context data 191 unsigned int &nItem, ///< Item number 192 unsigned int &nNewDataLen, ///< New data length 193 const char **ppData ///< New data 194 ); 195 196 /*!************************************************************************** 197 @brief Specify the number of custom counters and their definitions 198 ****************************************************************************/ 199 bool pplCountersCreate( 200 SSPSCommsData &sData, ///< Context data 201 const SSPSCommsCounterDef * const psCounterDefs, ///< Counter definitions 202 const unsigned int nCount ///< Number of counters 203 ); 204 205 /*!************************************************************************** 206 @brief Send an update for all the custom counters. The psCounterReadings array must be 207 nCount long. 208 ****************************************************************************/ 209 bool pplCountersUpdate( 210 SSPSCommsData &sData, ///< Context data 211 const unsigned int * const psCounterReadings ///< Counter readings array 212 ); 213 214 /*!************************************************************************** 215 @brief Force a cache flush. 216 @details Some implementations store data sends in the cache. If the data rate is low, the real 217 send of data can be significantly delayed. 218 If it is necessary to flush the cache, the best results are likely to be 219 achieved by calling this function with a frequency between once per second up to once per 220 frame. If data is sent extremely infrequently, this function could be 221 called once at the end of each bout of data send. 222 ****************************************************************************/ 223 bool pplSendFlush( 224 SSPSCommsData &sData ///< Context data 225 ); 226 227 /*! @} */ 228 229 #ifdef __cplusplus 230 } 231 #endif 232 233 #endif /* _PVRSCOPE_H_ */ 234 235 /***************************************************************************** 236 End of file (PVRScopeComms.h) 237 *****************************************************************************/ 238
