PlatformMethods.h - mozsearch

mozilla-central/gfx/angle/checkout/include/platform/PlatformMethods.h (file symbol)

Enable keyboard shortcuts

Source code

File a bug in Core :: Graphics

Revision control

Copy as Markdown

Other Tools

//

// Copyright 2015 The ANGLE Project Authors. All rights reserved.

// Use of this source code is governed by a BSD-style license that can be

// found in the LICENSE file.

// PlatformMethods.h: The public interface ANGLE exposes to the API layer, for

//   doing platform-specific tasks like gathering data, or for tracing.

#ifndef ANGLE_PLATFORMMETHODS_H

#define ANGLE_PLATFORMMETHODS_H

#include <stdint.h>

#include <stdlib.h>

#include <array>

#define EGL_PLATFORM_ANGLE_PLATFORM_METHODS_ANGLEX 0x6AFB

#if !defined(ANGLE_PLATFORM_EXPORT)

#    if defined(_WIN32)

#        if !defined(LIBANGLE_IMPLEMENTATION)

#            define ANGLE_PLATFORM_EXPORT __declspec(dllimport)

#        else

#            define ANGLE_PLATFORM_EXPORT __declspec(dllexport)

#        endif

#    elif defined(__GNUC__) || defined(__clang__)

#        define ANGLE_PLATFORM_EXPORT __attribute__((visibility("default")))

#    endif

#endif

#if !defined(ANGLE_PLATFORM_EXPORT)

#    define ANGLE_PLATFORM_EXPORT

#endif

#if defined(_WIN32)

#    define ANGLE_APIENTRY __stdcall

#else

#    define ANGLE_APIENTRY

#endif

namespace angle

struct FeaturesD3D;

struct FeaturesVk;

struct FeaturesMtl;

using TraceEventHandle = uint64_t;

using EGLDisplayType   = void *;

struct PlatformMethods;

// Use a C-like API to not trigger undefined calling behaviour.

// Avoid using decltype here to work around sanitizer limitations.

// TODO(jmadill): Use decltype here if/when UBSAN is fixed.

// System --------------------------------------------------------------

// Wall clock time in seconds since the epoch.

// TODO(jmadill): investigate using an ANGLE internal time library

using CurrentTimeFunc = double (*)(PlatformMethods *platform);

inline double DefaultCurrentTime(PlatformMethods *platform)

    return 0.0;

// Monotonically increasing time in seconds from an arbitrary fixed point in the past.

// This function is expected to return at least millisecond-precision values. For this reason,

// it is recommended that the fixed point be no further in the past than the epoch.

using MonotonicallyIncreasingTimeFunc = double (*)(PlatformMethods *platform);

inline double DefaultMonotonicallyIncreasingTime(PlatformMethods *platform)

    return 0.0;

// Logging ------------------------------------------------------------

// Log an error message within the platform implementation.

using LogErrorFunc = void (*)(PlatformMethods *platform, const char *errorMessage);

inline void DefaultLogError(PlatformMethods *platform, const char *errorMessage) {}

// Log a warning message within the platform implementation.

using LogWarningFunc = void (*)(PlatformMethods *platform, const char *warningMessage);

inline void DefaultLogWarning(PlatformMethods *platform, const char *warningMessage) {}

// Log an info message within the platform implementation.

using LogInfoFunc = void (*)(PlatformMethods *platform, const char *infoMessage);

inline void DefaultLogInfo(PlatformMethods *platform, const char *infoMessage) {}

// Tracing --------

// Get a pointer to the enabled state of the given trace category. The

// embedder can dynamically change the enabled state as trace event

// recording is started and stopped by the application. Only long-lived

// literal strings should be given as the category name. The implementation

// expects the returned pointer to be held permanently in a local static. If

// the unsigned char is non-zero, tracing is enabled. If tracing is enabled,

// addTraceEvent is expected to be called by the trace event macros.

using GetTraceCategoryEnabledFlagFunc = const unsigned char *(*)(PlatformMethods *platform,

                                                                 const char *categoryName);

inline const unsigned char *DefaultGetTraceCategoryEnabledFlag(PlatformMethods *platform,

                                                               const char *categoryName)

    return nullptr;

//

// Add a trace event to the platform tracing system. Depending on the actual

// enabled state, this event may be recorded or dropped.

// - phase specifies the type of event:

//   - BEGIN ('B'): Marks the beginning of a scoped event.

//   - END ('E'): Marks the end of a scoped event.

//   - COMPLETE ('X'): Marks the beginning of a scoped event, but doesn't

//     need a matching END event. Instead, at the end of the scope,

//     updateTraceEventDuration() must be called with the TraceEventHandle

//     returned from addTraceEvent().

//   - INSTANT ('I'): Standalone, instantaneous event.

//   - START ('S'): Marks the beginning of an asynchronous event (the end

//     event can occur in a different scope or thread). The id parameter is

//     used to match START/FINISH pairs.

//   - FINISH ('F'): Marks the end of an asynchronous event.

//   - COUNTER ('C'): Used to trace integer quantities that change over

//     time. The argument values are expected to be of type int.

//   - METADATA ('M'): Reserved for internal use.

// - categoryEnabled is the pointer returned by getTraceCategoryEnabledFlag.

// - name is the name of the event. Also used to match BEGIN/END and

//   START/FINISH pairs.

// - id optionally allows events of the same name to be distinguished from

//   each other. For example, to trace the construction and destruction of

//   objects, specify the pointer as the id parameter.

// - timestamp should be a time value returned from monotonicallyIncreasingTime.

// - numArgs specifies the number of elements in argNames, argTypes, and

//   argValues.

// - argNames is the array of argument names. Use long-lived literal strings

//   or specify the COPY flag.

// - argTypes is the array of argument types:

//   - BOOL (1): bool

//   - UINT (2): unsigned long long

//   - INT (3): long long

//   - DOUBLE (4): double

//   - POINTER (5): void*

//   - STRING (6): char* (long-lived null-terminated char* string)

//   - COPY_STRING (7): char* (temporary null-terminated char* string)

//   - CONVERTABLE (8): WebConvertableToTraceFormat

// - argValues is the array of argument values. Each value is the unsigned

//   long long member of a union of all supported types.

// - flags can be 0 or one or more of the following, ORed together:

//   - COPY (0x1): treat all strings (name, argNames and argValues of type

//     string) as temporary so that they will be copied by addTraceEvent.

//   - HAS_ID (0x2): use the id argument to uniquely identify the event for

//     matching with other events of the same name.

//   - MANGLE_ID (0x4): specify this flag if the id parameter is the value

//     of a pointer.

using AddTraceEventFunc = angle::TraceEventHandle (*)(PlatformMethods *platform,

                                                      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);

inline angle::TraceEventHandle DefaultAddTraceEvent(PlatformMethods *platform,

                                                    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)

    return 0;

// Set the duration field of a COMPLETE trace event.

using UpdateTraceEventDurationFunc = void (*)(PlatformMethods *platform,

                                              const unsigned char *categoryEnabledFlag,

                                              const char *name,

                                              angle::TraceEventHandle eventHandle);

inline void DefaultUpdateTraceEventDuration(PlatformMethods *platform,

                                            const unsigned char *categoryEnabledFlag,

                                            const char *name,

                                            angle::TraceEventHandle eventHandle)

{}

// Callbacks for reporting histogram data.

// CustomCounts histogram has exponential bucket sizes, so that min=1, max=1000000, bucketCount=50

// would do.

using HistogramCustomCountsFunc = void (*)(PlatformMethods *platform,

                                           const char *name,

                                           int sample,

                                           int min,

                                           int max,

                                           int bucketCount);

inline void DefaultHistogramCustomCounts(PlatformMethods *platform,

                                         const char *name,

                                         int sample,

                                         int min,

                                         int max,

                                         int bucketCount)

{}

// Enumeration histogram buckets are linear, boundaryValue should be larger than any possible sample

// value.

using HistogramEnumerationFunc = void (*)(PlatformMethods *platform,

                                          const char *name,

                                          int sample,

                                          int boundaryValue);

inline void DefaultHistogramEnumeration(PlatformMethods *platform,

                                        const char *name,

                                        int sample,

                                        int boundaryValue)

{}

// Unlike enumeration histograms, sparse histograms only allocate memory for non-empty buckets.

using HistogramSparseFunc = void (*)(PlatformMethods *platform, const char *name, int sample);

inline void DefaultHistogramSparse(PlatformMethods *platform, const char *name, int sample) {}

// Boolean histograms track two-state variables.

using HistogramBooleanFunc = void (*)(PlatformMethods *platform, const char *name, bool sample);

inline void DefaultHistogramBoolean(PlatformMethods *platform, const char *name, bool sample) {}

// Callback on a successful program link with the program binary. Can be used to store

// shaders to disk. Keys are a 160-bit SHA-1 hash.

using ProgramKeyType   = std::array<uint8_t, 20>;

using CacheProgramFunc = void (*)(PlatformMethods *platform,

                                  const ProgramKeyType &key,

                                  size_t programSize,

                                  const uint8_t *programBytes);

inline void DefaultCacheProgram(PlatformMethods *platform,

                                const ProgramKeyType &key,

                                size_t programSize,

                                const uint8_t *programBytes)

{}

using PostWorkerTaskCallback                       = void (*)(void *userData);

using PostWorkerTaskFunc                           = void (*)(PlatformMethods *platform,

                                    PostWorkerTaskCallback callback,

                                    void *userData);

constexpr PostWorkerTaskFunc DefaultPostWorkerTask = nullptr;

// Placeholder values where feature override callbacks used to be.  They are deprecated in favor of

// EGL_ANGLE_feature_control.  The placeholders are there to keep the layout of the PlatformMethods

// constant to support drop-in replacement of ANGLE's .so files in applications built with an older

// header.

using PlaceholderCallbackFunc = void (*)(...);

inline void DefaultPlaceholderCallback(...) {}

// Platform methods are enumerated here once.

#define ANGLE_PLATFORM_OP(OP)                                    \

    OP(currentTime, CurrentTime)                                 \

    OP(monotonicallyIncreasingTime, MonotonicallyIncreasingTime) \

    OP(logError, LogError)                                       \

    OP(logWarning, LogWarning)                                   \

    OP(logInfo, LogInfo)                                         \

    OP(getTraceCategoryEnabledFlag, GetTraceCategoryEnabledFlag) \

    OP(addTraceEvent, AddTraceEvent)                             \

    OP(updateTraceEventDuration, UpdateTraceEventDuration)       \

    OP(histogramCustomCounts, HistogramCustomCounts)             \

    OP(histogramEnumeration, HistogramEnumeration)               \

    OP(histogramSparse, HistogramSparse)                         \

    OP(histogramBoolean, HistogramBoolean)                       \

    OP(placeholder1, PlaceholderCallback)                        \

    OP(placeholder2, PlaceholderCallback)                        \

    OP(cacheProgram, CacheProgram)                               \

    OP(placeholder3, PlaceholderCallback)                        \

    OP(postWorkerTask, PostWorkerTask)

#define ANGLE_PLATFORM_METHOD_DEF(Name, CapsName) CapsName##Func Name = Default##CapsName;

struct ANGLE_PLATFORM_EXPORT PlatformMethods

    inline PlatformMethods();

    // User data pointer for any implementation specific members. Put it at the start of the

    // platform structure so it doesn't become overwritten if one version of the platform

    // adds or removes new members.

    void *context = 0;

    ANGLE_PLATFORM_OP(ANGLE_PLATFORM_METHOD_DEF)

};

inline PlatformMethods::PlatformMethods() = default;

#undef ANGLE_PLATFORM_METHOD_DEF

// Subtract one to account for the context pointer.

constexpr unsigned int g_NumPlatformMethods = (sizeof(PlatformMethods) / sizeof(uintptr_t)) - 1;

// No further uses of platform methods is allowed.  EGL extensions should be used instead.  While

// methods are being removed, use PlaceholderCallback to keep the layout of PlatformMethods

// constant.

static_assert(g_NumPlatformMethods == 17, "Avoid adding methods to PlatformMethods");

#define ANGLE_PLATFORM_METHOD_STRING(Name) #Name

#define ANGLE_PLATFORM_METHOD_STRING2(Name, CapsName) ANGLE_PLATFORM_METHOD_STRING(Name),

constexpr const char *const g_PlatformMethodNames[g_NumPlatformMethods] = {

    ANGLE_PLATFORM_OP(ANGLE_PLATFORM_METHOD_STRING2)};

#undef ANGLE_PLATFORM_METHOD_STRING2

#undef ANGLE_PLATFORM_METHOD_STRING

}  // namespace angle

extern "C" {

// Gets the platform methods on the passed-in EGL display. If the method name signature does not

// match the compiled signature for this ANGLE, false is returned. On success true is returned.

// The application should set any platform methods it cares about on the returned pointer.

// If display is not valid, behaviour is undefined.

ANGLE_PLATFORM_EXPORT bool ANGLE_APIENTRY ANGLEGetDisplayPlatform(angle::EGLDisplayType display,

                                                                  const char *const methodNames[],

                                                                  unsigned int methodNameCount,

                                                                  void *context,

                                                                  void *platformMethodsOut);

// Sets the platform methods back to their defaults.

// If display is not valid, behaviour is undefined.

ANGLE_PLATFORM_EXPORT void ANGLE_APIENTRY ANGLEResetDisplayPlatform(angle::EGLDisplayType display);

}  // extern "C"

namespace angle

typedef bool(ANGLE_APIENTRY *GetDisplayPlatformFunc)(angle::EGLDisplayType,

                                                     const char *const *,

                                                     unsigned int,

                                                     void *,

                                                     void *);

typedef void(ANGLE_APIENTRY *ResetDisplayPlatformFunc)(angle::EGLDisplayType);

}  // namespace angle

// This function is not exported

angle::PlatformMethods *ANGLEPlatformCurrent();

#endif  // ANGLE_PLATFORMMETHODS_H