1 // 2 // Copyright (c) 2015 The ANGLE Project Authors. All rights reserved. 3 // Use of this source code is governed by a BSD-style license that can be 4 // found in the LICENSE file. 5 6 // Platform.h: The public interface ANGLE exposes to the API layer, for 7 // doing platform-specific tasks like gathering data, or for tracing. 8 9 #ifndef ANGLE_PLATFORM_H 10 #define ANGLE_PLATFORM_H 11 12 #include <stdint.h> 13 14 #if defined(_WIN32) 15 # if !defined(LIBANGLE_IMPLEMENTATION) 16 # define ANGLE_PLATFORM_EXPORT __declspec(dllimport) 17 # endif 18 #elif defined(__GNUC__) 19 # if defined(LIBANGLE_IMPLEMENTATION) 20 # define ANGLE_PLATFORM_EXPORT __attribute__((visibility ("default"))) 21 # endif 22 #endif 23 #if !defined(ANGLE_PLATFORM_EXPORT) 24 # define ANGLE_PLATFORM_EXPORT 25 #endif 26 27 #if defined(_WIN32) 28 # define ANGLE_APIENTRY __stdcall 29 #else 30 # define ANGLE_APIENTRY 31 #endif 32 33 namespace angle 34 { 35 36 class Platform 37 { 38 public: 39 40 // System -------------------------------------------------------------- 41 42 // Wall clock time in seconds since the epoch. 43 // TODO(jmadill): investigate using an ANGLE internal time library currentTime()44 virtual double currentTime() { return 0; } 45 46 // Monotonically increasing time in seconds from an arbitrary fixed point in the past. 47 // This function is expected to return at least millisecond-precision values. For this reason, 48 // it is recommended that the fixed point be no further in the past than the epoch. monotonicallyIncreasingTime()49 virtual double monotonicallyIncreasingTime() { return 0; } 50 51 // Logging ------------------------------------------------------------ 52 53 // Log an error message within the platform implementation. logError(const char * errorMessage)54 virtual void logError(const char *errorMessage) {} 55 56 // Log a warning message within the platform implementation. logWarning(const char * warningMessage)57 virtual void logWarning(const char *warningMessage) {} 58 59 // Log an info message within the platform implementation. logInfo(const char * infoMessage)60 virtual void logInfo(const char *infoMessage) {} 61 62 // Tracing -------- 63 64 // Get a pointer to the enabled state of the given trace category. The 65 // embedder can dynamically change the enabled state as trace event 66 // recording is started and stopped by the application. Only long-lived 67 // literal strings should be given as the category name. The implementation 68 // expects the returned pointer to be held permanently in a local static. If 69 // the unsigned char is non-zero, tracing is enabled. If tracing is enabled, 70 // addTraceEvent is expected to be called by the trace event macros. getTraceCategoryEnabledFlag(const char * categoryName)71 virtual const unsigned char *getTraceCategoryEnabledFlag(const char *categoryName) { return 0; } 72 73 typedef uint64_t TraceEventHandle; 74 75 // Add a trace event to the platform tracing system. Depending on the actual 76 // enabled state, this event may be recorded or dropped. 77 // - phase specifies the type of event: 78 // - BEGIN ('B'): Marks the beginning of a scoped event. 79 // - END ('E'): Marks the end of a scoped event. 80 // - COMPLETE ('X'): Marks the beginning of a scoped event, but doesn't 81 // need a matching END event. Instead, at the end of the scope, 82 // updateTraceEventDuration() must be called with the TraceEventHandle 83 // returned from addTraceEvent(). 84 // - INSTANT ('I'): Standalone, instantaneous event. 85 // - START ('S'): Marks the beginning of an asynchronous event (the end 86 // event can occur in a different scope or thread). The id parameter is 87 // used to match START/FINISH pairs. 88 // - FINISH ('F'): Marks the end of an asynchronous event. 89 // - COUNTER ('C'): Used to trace integer quantities that change over 90 // time. The argument values are expected to be of type int. 91 // - METADATA ('M'): Reserved for internal use. 92 // - categoryEnabled is the pointer returned by getTraceCategoryEnabledFlag. 93 // - name is the name of the event. Also used to match BEGIN/END and 94 // START/FINISH pairs. 95 // - id optionally allows events of the same name to be distinguished from 96 // each other. For example, to trace the consutruction and destruction of 97 // objects, specify the pointer as the id parameter. 98 // - timestamp should be a time value returned from monotonicallyIncreasingTime. 99 // - numArgs specifies the number of elements in argNames, argTypes, and 100 // argValues. 101 // - argNames is the array of argument names. Use long-lived literal strings 102 // or specify the COPY flag. 103 // - argTypes is the array of argument types: 104 // - BOOL (1): bool 105 // - UINT (2): unsigned long long 106 // - INT (3): long long 107 // - DOUBLE (4): double 108 // - POINTER (5): void* 109 // - STRING (6): char* (long-lived null-terminated char* string) 110 // - COPY_STRING (7): char* (temporary null-terminated char* string) 111 // - CONVERTABLE (8): WebConvertableToTraceFormat 112 // - argValues is the array of argument values. Each value is the unsigned 113 // long long member of a union of all supported types. 114 // - flags can be 0 or one or more of the following, ORed together: 115 // - COPY (0x1): treat all strings (name, argNames and argValues of type 116 // string) as temporary so that they will be copied by addTraceEvent. 117 // - HAS_ID (0x2): use the id argument to uniquely identify the event for 118 // matching with other events of the same name. 119 // - MANGLE_ID (0x4): specify this flag if the id parameter is the value 120 // of a pointer. addTraceEvent(char phase,const unsigned char * categoryEnabledFlag,const char * name,unsigned long long id,double timestamp,int numArgs,const char ** argNames,const unsigned char * argTypes,const unsigned long long * argValues,unsigned char flags)121 virtual TraceEventHandle addTraceEvent(char phase, 122 const unsigned char *categoryEnabledFlag, 123 const char *name, 124 unsigned long long id, 125 double timestamp, 126 int numArgs, 127 const char **argNames, 128 const unsigned char *argTypes, 129 const unsigned long long *argValues, 130 unsigned char flags) 131 { 132 return 0; 133 } 134 135 // Set the duration field of a COMPLETE trace event. updateTraceEventDuration(const unsigned char * categoryEnabledFlag,const char * name,TraceEventHandle eventHandle)136 virtual void updateTraceEventDuration(const unsigned char *categoryEnabledFlag, const char *name, TraceEventHandle eventHandle) { } 137 138 // Callbacks for reporting histogram data. 139 // CustomCounts histogram has exponential bucket sizes, so that min=1, max=1000000, bucketCount=50 would do. histogramCustomCounts(const char * name,int sample,int min,int max,int bucketCount)140 virtual void histogramCustomCounts(const char *name, int sample, int min, int max, int bucketCount) { } 141 // Enumeration histogram buckets are linear, boundaryValue should be larger than any possible sample value. histogramEnumeration(const char * name,int sample,int boundaryValue)142 virtual void histogramEnumeration(const char *name, int sample, int boundaryValue) { } 143 // Unlike enumeration histograms, sparse histograms only allocate memory for non-empty buckets. histogramSparse(const char * name,int sample)144 virtual void histogramSparse(const char *name, int sample) { } 145 // Boolean histograms track two-state variables. histogramBoolean(const char * name,bool sample)146 virtual void histogramBoolean(const char *name, bool sample) { } 147 148 protected: ~Platform()149 virtual ~Platform() { } 150 }; 151 152 } 153 154 extern "C" 155 { 156 157 typedef void (ANGLE_APIENTRY *ANGLEPlatformInitializeFunc)(angle::Platform*); 158 ANGLE_PLATFORM_EXPORT void ANGLE_APIENTRY ANGLEPlatformInitialize(angle::Platform*); 159 160 typedef void (ANGLE_APIENTRY *ANGLEPlatformShutdownFunc)(); 161 ANGLE_PLATFORM_EXPORT void ANGLE_APIENTRY ANGLEPlatformShutdown(); 162 163 typedef angle::Platform *(ANGLE_APIENTRY *ANGLEPlatformCurrentFunc)(); 164 ANGLE_PLATFORM_EXPORT angle::Platform *ANGLE_APIENTRY ANGLEPlatformCurrent(); 165 166 } 167 168 #endif // ANGLE_PLATFORM_H 169