/*
 * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

#ifndef EGL_EXTERNAL_PLATFORM_H
#define EGL_EXTERNAL_PLATFORM_H

#include <EGL/egl.h>
#include <EGL/eglext.h>
#include "eglexternalplatformversion.h"

/* EGL external platform interface objects */
typedef struct EGLExtPlatformExports EGLExtPlatformExports;
typedef struct EGLExtPlatform        EGLExtPlatform;
typedef struct EGLExtDriver          EGLExtDriver;

/* EGLExtPlatformString enum. This indicates what string to query through
 * queryString() */
typedef enum {
    /*
     * Platform client extensions
     *
     * Returns a extension string including the specific platform client
     * extensions. E.g. EGL_EXT_platform_wayland on Wayland platform.
     *
     * The <dpy> parameter is EGL_NO_DISPLAY.
     */
    EGL_EXT_PLATFORM_PLATFORM_CLIENT_EXTENSIONS = 0,

    /*
     * Display extensions
     *
     * Returns a extension string including all display extensions supported on
     * the given display by the external platform implementation.
     */
    EGL_EXT_PLATFORM_DISPLAY_EXTENSIONS,

    EGL_EXT_PLATFORM_STRING_NAME_COUNT
} EGLExtPlatformString;


/*
 * loadEGLExternalPlatform()
 *
 * Loads the EGL external platform and returns a EGLExtPlatform object where
 * external platform data and exported functions have been properly set
 * according to the given major and minor version numbers
 *
 * If a compatible external platform is found for <major>.<minor>, EGL_TRUE is
 * returned and <platform> is properly initialized. Otherwise, EGL_FALSE is
 * returned and <platform> remains unchanged
 *
 * A reference to the underlying EGL implementation that must be used is passed
 * in <driver>.
 */
typedef EGLBoolean (*PEGLEXTFNLOADEGLEXTERNALPLATFORM) (int major, int minor, const EGLExtDriver *driver, EGLExtPlatform *platform);

/*
 * unloadEGLExternalPlatform()
 *
 * Unloads the EGL external platform, freeing any resources associated to the
 * given platform data structure that may have been allocated and not yet freed.
 *
 * If all resources are properly freed, EGL_TRUE is returned and the given
 * platform data pointer becomes invalid. Otherwise, EGL_FALSE is returned.
 */
typedef EGLBoolean (*PEGLEXTFNUNLOADEGLEXTERNALPLATFORM) (void *platformData);

/*
 * getHookAddress()
 *
 * The EGL external platform interface defines a minimum set of functions that
 * must be provided by any EGL external platform at loadEGLExternalPlatform()
 * time.
 *
 * However, most of the other EGL functions can be overwritten by an EGL
 * external platform.
 *
 * The EGL implementation will call into getHookAddress() to retrieve any
 * additional EGL function that the external platform may implement. Its
 * behavior is comparable to eglGetProcAddress().
 *
 * Returns the hook address if the given functions is implemented; otherwise,
 * returns NULL.
 */
typedef void* (*PEGLEXTFNGETHOOKADDRESS) (void *platformData, const char *name);

/*
 * isValidNativeDisplay()
 *
 * Validity check function for a native display. It will return EGL_TRUE if the
 * given native display is valid and belongs to the external platform
 * implementation; otherwise, it will return EGL_FALSE.
 */
typedef EGLBoolean (*PEGLEXTFNISVALIDNATIVEDISPLAY) (void *platformData, void *nativeDisplay);

/*
 * getPlatformDisplay()
 *
 * Same as eglGetPlatformDisplay()
 */
typedef EGLDisplay (*PEGLEXTFNGETPLATFORMDISPLAY) (void *platformData, EGLenum platform, void *nativeDisplay, const EGLAttrib* attribs);

/*
 * queryString()
 *
 * Similar to eglQueryString(), but takes its own enumeration as the string name
 * parameter.
 *
 * Returns the appropriate extension string which is supported by the external
 * platform. See descriptions of EGLExtPlatformString enums for more details.
 */
typedef const char * (*PEGLEXTFNQUERYSTRING) (void *platformData, EGLDisplay dpy, EGLExtPlatformString name);

/*
 * getInternalHandle()
 *
 * Conversion function from an EGL external object handle to its corresponding
 * EGL internal one. It will return the internal EGL object handle if the given
 * external handle is valid and belongs to the given EGLDisplay; otherwise, it
 * will return NULL.
 *
 * Note that the object handle type must be provided by the caller. Its value
 * must be one of the object type enums as defined in EGL_KHR_debug.
 */
typedef void* (*PEGLEXTFNGETINTERNALHANDLE) (EGLDisplay dpy, EGLenum type, void *handle);

/*
 * getObjectLabel()
 *
 * Returns an EGL external object label previously attached with
 * eglLabelObjectKHR() from EGL_KHR_debug.
 *
 * Note that the object handle type must be provided by the caller. Its value
 * must be one of the object type enums as defined in EGL_KHR_debug.
 */
typedef void* (*PEGLEXTFNGETOBJECTLABEL) (EGLDisplay dpy, EGLenum type, void *handle);


/*
 * EGLExtPlatformExports definition. This is the exports table an external
 * platform must fill out and make available for the EGL implementation to use
 */
struct EGLExtPlatformExports {
    PEGLEXTFNUNLOADEGLEXTERNALPLATFORM unloadEGLExternalPlatform;
    PEGLEXTFNGETHOOKADDRESS            getHookAddress;

    PEGLEXTFNISVALIDNATIVEDISPLAY      isValidNativeDisplay;
    PEGLEXTFNGETPLATFORMDISPLAY        getPlatformDisplay;

    PEGLEXTFNQUERYSTRING               queryString;

    PEGLEXTFNGETINTERNALHANDLE         getInternalHandle;

    PEGLEXTFNGETOBJECTLABEL            getObjectLabel;
};

/*
 * EGLExtPlatform definition. This is common to all external platforms
 *
 * Fields:
 *  - major/minor: External platform major/minor version number. Specify the EGL
 *                 external platform interface version number the given platform
 *                 implements. They are tied to EGL external platform interface
 *                 changes.
 *  - micro:       External platform micro version number. Similar to
 *                 major/minor numbers, but it is tied to specific external
 *                 platform implementation changes.
 *  - platform:    EGL platform enumeration the corresponding external platform
 *                 implements.
 *  - data:        Opaque pointer to platform specific data. At platform
 *                 load time, the external platform can initialize its own data
 *                 structure to store any information that may be required by
 *                 any function that does not take an EGLDisplay or the display
 *                 belongs to another platform.
 *  - exports:     External platform exports table.
 */
struct EGLExtPlatform {
    struct {
        int major;
        int minor;
        int micro;
    }                      version;
    EGLenum                platform;
    void                  *data;
    EGLExtPlatformExports  exports;
};


/*
 * getProcAddress()
 *
 * Equivalent to eglGetProcAddress() to fetch EGL methods provided by a
 * specific EGL driver.
 */
typedef void* (*PEGLEXTFNGETPROCADDRESS) (const char *name);

/*
 * setError()
 *
 * Sets the last EGL error, which can be queried with eglGetError() later on. It
 * also calls the EGL_KHR_debug callback if such extension is supported by the
 * driver.
 *
 * Takes the EGL error code and both message type and string as defined in
 * EGL_KHR_debug for the debug callback function.
 */
typedef void (*PEGLEXTFNSETERROR) (EGLint error, EGLint msgType, const char *msg);

/*
 * debugMessage()
 *
 * Calls the EGL_KHR_debug callback if such extension is supported by the
 * driver.
 *
 * Takes both message type and string as defined in EGL_KHR_debug for the debug
 * callback function.
 */
typedef void* (*PEGLEXTFNDEBUGMESSAGE) (EGLint msgType, const char *msg);

/*
 * streamSwapInterval()
 *
 * Handle swapinterval on the EGLStream consumer side. Should be a noop for
 * any consumer that does not present directly to a display.
 *
 * Takes the stream handle and a pointer to the interval value as parameters.
 *
 * Returns one of the following EGL error codes:
 *  - EGL_SUCCESS:    The interval setting operation succeeded (or noop).
 *  - EGL_BAD_MATCH:  A server-side interval override is in place. The override
 *                    value is returned in the <interval> parameter.
 *  - EGL_BAD_ACCESS: The interval setting operation failed.
 */
typedef EGLint (*PEGLEXTFNSTREAMSWAPINTERVAL) (EGLStreamKHR stream, int *interval);

/*
 * EGLExtDriver definition. The EGL external driver is the component in
 * charge of dispatching EGL calls to the underlying EGL implementation.
 */
struct EGLExtDriver {
    PEGLEXTFNGETPROCADDRESS     getProcAddress;
    PEGLEXTFNSETERROR           setError;
    PEGLEXTFNDEBUGMESSAGE       debugMessage;
    PEGLEXTFNSTREAMSWAPINTERVAL streamSwapInterval;
#if EGL_EXTERNAL_PLATFORM_HAS(DRIVER_VERSION)
    int major;
    int minor;
#endif
};

#endif // EGL_EXTERNAL_PLATFORM_H