298 lines
13 KiB
Objective-C
Executable File
298 lines
13 KiB
Objective-C
Executable File
/*!***********************************************************************
|
|
|
|
@file PVRScopeComms.h
|
|
@copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved.
|
|
@brief PVRScopeComms header file. @copybrief ScopeComms
|
|
|
|
**************************************************************************/
|
|
|
|
#ifndef _PVRSCOPECOMMS_H_
|
|
#define _PVRSCOPECOMMS_H_
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*
|
|
PVRPerfServer and PVRTune communications
|
|
*/
|
|
|
|
/*!
|
|
@addtogroup ScopeComms PVRScopeComms
|
|
@brief The PVRScopeComms functionality of PVRScope allows an application to send user defined information to
|
|
PVRTune via PVRPerfServer, both as counters and marks, or as editable data that can be
|
|
passed back to the application.
|
|
@details PVRScopeComms has the following limitations:
|
|
\li PVRPerfServer must be running on the host device if a @ref ScopeComms enabled
|
|
application wishes to send custom counters or marks to PVRTune. If the application in
|
|
question also wishes to communicate with PVRScopeServices without experiencing any
|
|
undesired behaviour PVRPerfServer should be run with the '--disable-hwperf' flag.
|
|
\li The following types may be sent: Boolean, Enumerator, Float, Integer, String.
|
|
@{
|
|
*/
|
|
|
|
/****************************************************************************
|
|
** Enums
|
|
****************************************************************************/
|
|
|
|
/*!**************************************************************************
|
|
@enum ESPSCommsLibType
|
|
@brief Each editable library item has a data type associated with it
|
|
****************************************************************************/
|
|
///
|
|
enum ESPSCommsLibType
|
|
{
|
|
eSPSCommsLibTypeString, ///< data is string (NOT NULL-terminated, use length parameter)
|
|
eSPSCommsLibTypeFloat, ///< data is SSPSCommsLibraryTypeFloat
|
|
eSPSCommsLibTypeInt, ///< data is SSPSCommsLibraryTypeInt
|
|
eSPSCommsLibTypeEnum, ///< data is string (NOT NULL-terminated, use length parameter). First line is selection number, subsequent lines are available options.
|
|
eSPSCommsLibTypeBool ///< data is SSPSCommsLibraryTypeBool
|
|
};
|
|
|
|
/****************************************************************************
|
|
** Structures
|
|
****************************************************************************/
|
|
|
|
// Internal implementation data
|
|
struct SSPSCommsData;
|
|
|
|
/*!**************************************************************************
|
|
@struct SSPSCommsLibraryItem
|
|
@brief Definition of one editable library item
|
|
****************************************************************************/
|
|
struct SSPSCommsLibraryItem
|
|
{
|
|
|
|
const char *pszName; ///< Item name. If dots are used, PVRTune could show these as a foldable tree view.
|
|
unsigned int nNameLength; ///< Item name length
|
|
|
|
enum ESPSCommsLibType eType; ///< Item type
|
|
|
|
const char *pData; ///< Item data
|
|
unsigned int nDataLength; ///< Item data length
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@struct SSPSCommsLibraryTypeFloat
|
|
@brief Current, minimum and maximum values for an editable library item of type float
|
|
****************************************************************************/
|
|
struct SSPSCommsLibraryTypeFloat
|
|
{
|
|
float fCurrent; ///< Current value
|
|
float fMin; ///< Minimal value
|
|
float fMax; ///< Maximum value
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@struct SSPSCommsLibraryTypeInt
|
|
@brief Current, minimum and maximum values for an editable library item of type int
|
|
****************************************************************************/
|
|
struct SSPSCommsLibraryTypeInt
|
|
{
|
|
int nCurrent; ///< Current value
|
|
int nMin; ///< Minimal value
|
|
int nMax; ///< Maximum value
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@struct SSPSCommsLibraryTypeBool
|
|
@brief Current value for an editable library item of type bool
|
|
****************************************************************************/
|
|
struct SSPSCommsLibraryTypeBool
|
|
{
|
|
int nBoolValue; ///< Boolean value (zero = false)
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@struct SSPSCommsCounterDef
|
|
@brief Definition of one custom counter
|
|
****************************************************************************/
|
|
struct SSPSCommsCounterDef
|
|
{
|
|
const char *pszName; ///< Custom counter name
|
|
unsigned int nNameLength; ///< Custom counter name length
|
|
};
|
|
|
|
/****************************************************************************
|
|
** Declarations
|
|
****************************************************************************/
|
|
|
|
|
|
/*!**************************************************************************
|
|
@brief Initialise @ref ScopeComms
|
|
@return @ref ScopeComms data.
|
|
****************************************************************************/
|
|
struct SSPSCommsData *pplInitialise(
|
|
const char * const psName, ///< String to describe the application
|
|
const unsigned int nNameLen ///< String length
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Shutdown or de-initialise the remote control section of PVRScope.
|
|
****************************************************************************/
|
|
void pplShutdown(
|
|
struct SSPSCommsData *psData ///< Context data
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Optional function. Sleeps until there is a connection to
|
|
PVRPerfServer, or time-out. Normally, each thread will wait for
|
|
its own connection, and each time-out will naturally happen in
|
|
parallel. But if a thread happens to have multiple connections,
|
|
N, then waiting for them all [in serial] with time-out M would
|
|
take N*M ms if they were all to time-out (e.g. PVRPerfServer is
|
|
not running); therefore this function, is designed to allow an
|
|
entire array of connections to be waited upon simultaneously.
|
|
****************************************************************************/
|
|
void pplWaitForConnection(
|
|
struct SSPSCommsData * const psData, ///< Array of context data pointers
|
|
int * const pnBoolResults, ///< Array of results - false (0) if timeout
|
|
const unsigned int nCount, ///< Array length
|
|
const unsigned int nTimeOutMS ///< Time-out length in milliseconds
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Query for the time. Units are microseconds, resolution is undefined.
|
|
****************************************************************************/
|
|
unsigned int pplGetTimeUS(
|
|
struct SSPSCommsData * const psData ///< Context data
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Send a time-stamped string marker to be displayed in PVRTune.
|
|
@details Examples might be:
|
|
\li switching to outdoor renderer
|
|
\li starting benchmark test N
|
|
****************************************************************************/
|
|
int pplSendMark(
|
|
struct SSPSCommsData * const psData, ///< Context data
|
|
const char * const psString, ///< String to send
|
|
const unsigned int nLen ///< String length
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Send a time-stamped begin marker to PVRTune.
|
|
@details Every begin must at some point be followed by an end; begin/end
|
|
pairs can be nested. PVRTune will show these as an activity
|
|
timeline, using a "flame graph" style when there is nesting.
|
|
See also the CPPLProcessingScoped helper class.
|
|
****************************************************************************/
|
|
int pplSendProcessingBegin(
|
|
struct SSPSCommsData * const psData, ///< Context data
|
|
const char * const psString, ///< Name of the processing block
|
|
const unsigned int nLen, ///< String length
|
|
const unsigned int nFrame ///< Iteration (or frame) number, by which processes can be grouped.
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Send a time-stamped end marker to PVRTune.
|
|
@details Every begin must at some point be followed by an end; begin/end
|
|
pairs can be nested. PVRTune will show these as an activity
|
|
timeline, using a "flame graph" style when there is nesting.
|
|
See also the CPPLProcessingScoped helper class.
|
|
****************************************************************************/
|
|
int pplSendProcessingEnd(
|
|
struct SSPSCommsData * const psData ///< Context data
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Create a library of remotely editable items
|
|
****************************************************************************/
|
|
int pplLibraryCreate(
|
|
struct SSPSCommsData * const psData, ///< Context data
|
|
const struct SSPSCommsLibraryItem * const pItems, ///< Editable items
|
|
const unsigned int nItemCount ///< Number of items
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Query to see whether a library item has been edited, and also
|
|
retrieve the new data.
|
|
****************************************************************************/
|
|
int pplLibraryDirtyGetFirst(
|
|
struct SSPSCommsData * const psData, ///< Context data
|
|
unsigned int * const pnItem, ///< Item number
|
|
unsigned int * const pnNewDataLen, ///< New data length
|
|
const char **ppData ///< New data
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Specify the number of custom counters and their definitions
|
|
****************************************************************************/
|
|
int pplCountersCreate(
|
|
struct SSPSCommsData * const psData, ///< Context data
|
|
const struct SSPSCommsCounterDef * const psCounterDefs, ///< Counter definitions
|
|
const unsigned int nCount ///< Number of counters
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Send an update for all the custom counters. The
|
|
psCounterReadings array must be nCount long.
|
|
****************************************************************************/
|
|
int pplCountersUpdate(
|
|
struct SSPSCommsData * const psData, ///< Context data
|
|
const unsigned int * const psCounterReadings ///< Counter readings array
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Force a cache flush.
|
|
@details Some implementations store data sends in the cache. If the data
|
|
rate is low, the real send of data can be significantly
|
|
delayed.
|
|
If it is necessary to flush the cache, the best results are
|
|
likely to be achieved by calling this function with a frequency
|
|
between once per second up to once per frame. If data is sent
|
|
extremely infrequently, this function could be called once at
|
|
the end of each bout of data send.
|
|
****************************************************************************/
|
|
int pplSendFlush(
|
|
struct SSPSCommsData * const psData ///< Context data
|
|
);
|
|
|
|
/*! @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
|
|
/*!**************************************************************************
|
|
@class CPPLProcessingScoped
|
|
@brief Helper class which will send a processing begin/end pair around
|
|
its scope. You would typically instantiate these at the top of
|
|
a function or after the opening curly-brace of a new scope
|
|
within a function.
|
|
****************************************************************************/
|
|
class CPPLProcessingScoped
|
|
{
|
|
protected:
|
|
SSPSCommsData * const m_psData; ///< Context data
|
|
|
|
public:
|
|
CPPLProcessingScoped(
|
|
SSPSCommsData * const psData, ///< Context data
|
|
const char * const psString, ///< Name of the processing block
|
|
const unsigned int nLen, ///< String length
|
|
const unsigned int nFrame=0 ///< Iteration (or frame) number, by which processes can be grouped.
|
|
)
|
|
: m_psData(psData)
|
|
{
|
|
if (m_psData)
|
|
pplSendProcessingBegin(m_psData, psString, nLen, nFrame);
|
|
}
|
|
|
|
~CPPLProcessingScoped()
|
|
{
|
|
if (m_psData)
|
|
pplSendProcessingEnd(m_psData);
|
|
}
|
|
|
|
private:
|
|
CPPLProcessingScoped(const CPPLProcessingScoped&); // Prevent copy-construction
|
|
CPPLProcessingScoped& operator=(const CPPLProcessingScoped&); // Prevent assignment
|
|
};
|
|
#endif
|
|
|
|
#endif /* _PVRSCOPECOMMS_H_ */
|
|
|
|
/*****************************************************************************
|
|
End of file (PVRScopeComms.h)
|
|
*****************************************************************************/
|