/**
 * Copyright ©2020-2023 Moore Threads Technology Co., Ltd ("Moore Threads"). All rights reserved.
 *
 * This software ("this software and its documentations" or "the software") is
 * protected by Copyright and the information contained herein is confidential.
 *
 * The software contained herein is PROPRIETARY to Moore Threads and is being provided under the terms and 
 * conditions of a form of Moore Threads software license agreement by and
 * between Moore Threads and Licensee ("License Agreement") or electronically
 * accepted by Licensee. Notwithstanding any terms or conditions to
 * the contrary in the License Agreement, copy or disclosure
 * of the software to any third party without the express
 * written consent of Moore Threads is prohibited.
 *
 * NOTWITHSTANDING ANY TERMS OR CONDITIONS TO THE CONTRARY IN THE
 * LICENSE AGREEMENT, MOORE THREADS MAKES NO REPRESENTATION ABOUT ANY WARRANTIES, INCLUDING BUT NOT LIMITED TO THE
 * SUITABILITY OF THE SOFTWARE FOR ANY PURPOSE. IT IS
 * PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY OF ANY KIND.
 * MOORE THREADS DISCLAIMS ALL WARRANTIES WITH REGARD TO THE
 * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY,
 * NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
 * NOTWITHSTANDING ANY TERMS OR CONDITIONS TO THE CONTRARY IN THE
 * LICENSE AGREEMENT, IN NO EVENT SHALL MOORE THREADS BE LIABLE FOR ANY
 * SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, OR ANY
 * DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
 * WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
 * OF THE SOFTWARE.
 **/

#ifndef MTAPI_H_
#define MTAPI_H_

#ifdef __cplusplus
extern "C" {
#endif

#ifdef MTAPI_EXPORT
    #define MTAPI __declspec(dllexport)
#else
    #define MTAPI __declspec(dllimport)
#endif

/*! \mainpage Moore Threads MTAPI
 *
 * \section intro_sec Introduction
 *
 * MTAPI is Moore Threads's core software development kit that allows direct access to Moore Threads GPUs and drivers on all Microsoft® Windows® platforms.
 *
 */

/***************************************************************************************************/
/** @defgroup mtapi1 Constant Definitions
 *  @{
 */
/***************************************************************************************************/

/** 
 * Returns values for MTAPI API calls.
 */
typedef enum
{
    MTAPI_SUCCESS = 0,               //!< The operation was successful.
    MTAPI_ERROR_DRIVER_NOT_LOADED,   //!< The Moore Threads driver is not loaded.
    MTAPI_ERROR_DRIVER_FAILURE,      //!< Access to the driver failed.
    MTAPI_ERROR_INVALID_ARGUMENT,    //!< One or more supplied arguments are invalid.
    MTAPI_ERROR_NOT_SUPPORTED,       //!< The requested operation is not available on the target device.
    MTAPI_ERROR_NO_PERMISSION,       //!< The current user does not have permission to operate.
    MTAPI_ERROR_INSUFFICIENT_SIZE,   //!< The space allocated by the user is insufficient to hold the requested data.
    MTAPI_ERROR_NOT_FOUND,           //!< A query to find a resource was unsuccessful.
    MTAPI_ERROR_INSUFFICIENT_MEMORY, //!< There is not enough system memory to finish the operation.
    MTAPI_ERROR_UNKNOWN = 999        //!< An internal, unspecified error occurred.
} MtapiStatus;

/***********************************/
/** @}
 */
/***********************************/


/***************************************************************************************************/
/** @defgroup mtapi2 Functional Structure Definitions
 *  @{
 */
/***************************************************************************************************/
/** 
 * Custom resolutions.
*/
typedef struct _MtapiCustomDisplay
{
    unsigned int hDisplay;          //!< The horizontal resolution.
    unsigned int vDisplay;          //!< The vertical resolution.
    unsigned int vRefresh;          //!< The refresh rate.
}MtapiCustomDisplay;

/***********************************/
/** @}
 */
/***********************************/


/***************************************************************************************************/
/** @defgroup mtapi3 Opaque Data Structure Definitions
 *  @{
 */
/***************************************************************************************************/
/**
 * The physical GPU opaque data structure.
*/
typedef struct MtapiPhysicalGpu* MtapiPhysicalGpuHandle;

/***********************************/
/** @}
 */
/***********************************/


/***************************************************************************************************/
/** @defgroup mtapi4 Library Functions
 *  @{
 */
/***************************************************************************************************/

/**
 * Enumerates all physical GPU opaque objects and prepares resources. Upon success, the initialized objects can be used for further 
 * access to other functions. 
 *
 * For all products.
 * 
 * The array of \ref MtapiPhysicalGpuHandle should be allocated by the user. The opaque objects of \ref MtapiPhysicalGpuHandle are allocated 
 * internally by the MTAPI library. Use \ref mtapiPhysicalGpuFree() to release its resources when they are not needed any longer.
 * 
 * @param handles                                    [inout] An array of \ref MtapiPhysicalGpuHandle pointers to the physical GPU opaque objects that are allocated and initialized. 
 *                                                   Can be NULL to retrieve the \a num first.
 * @param num                                        [inout] The number of MtapiPhysicalGpuHandle.
 * 
 * @return 
 *         - \ref MTAPI_SUCCESS                      if an array of physical GPU opaque objects has been properly initialized.
 *         - \ref MTAPI_ERROR_INVALID_ARGUMENT       if \a num is NULL.
 *         - \ref MTAPI_ERROR_INSUFFICIENT_MEMORY    if the system is running out of memory.
 *         - \ref MTAPI_ERROR_UNKNOWN                if any unexpected error occurred.
 */
MtapiStatus MTAPI mtapiEnumPhysicalGpus(MtapiPhysicalGpuHandle* handles, unsigned int* num);

/**
 * Frees a physical GPU opaque object that is previously initialized by \ref mtapiEnumPhysicalGpus() and releases its resources.
 * This opaque object cannot be used with other functions any longer unless being initialized again.
 *
 * For all products. 
 *
 * @param handle                                   [in] A pointer to the physical GPU opaque object that needs to be freed.
 * 
 * @return 
 *         - \ref MTAPI_SUCCESS                  if the physical GPU opaque object has been properly freed.
 *         - \ref MTAPI_ERROR_INVALID_ARGUMENT   if \a handle is NULL.
 *         - \ref MTAPI_ERROR_UNKNOWN            if any unexpected error occurred.
 */
void MTAPI mtapiPhysicalGpuFree(MtapiPhysicalGpuHandle handle);

/**
 * Gets the active display IDs connected to the physical GPU.
 *
 * For all products. 
 *
 * @param handle                                   [in]     A pointer to the physical GPU opaque object.
 * @param DisplayIds                               [inout]  The active display IDs connected to the physical GPU. Can be NULL to retrieve the \a num first.
 * @param num                                      [inout]  The number of \a DisplayIds.
 * 
 * @return 
 *         - \ref MTAPI_SUCCESS                  if physical GPU opaque object has been properly freed.
 *         - \ref MTAPI_ERROR_INVALID_ARGUMENT   if \a num or  \a handle is NULL.
 *         - \ref MTAPI_ERROR_UNKNOWN            if any unexpected error occurred.
 */
MtapiStatus MTAPI mtapiPhysicalGpuGetConnectedDisplay(MtapiPhysicalGpuHandle handle,  unsigned int* DisplayIds, unsigned int* num);

/**
 * Sets custom resolutions on the specified display.
 *
 * For all products. 
 *
 * @param displayId                                [in]     The ID of the specified display.
 * @param customDisplay                            [in]     The custom display parameters. Limits:
 *                                                          1. 640 <= hDisplay <= 1920
 *                                                          2. 480 <= vDisplay <= 1200
 *                                                          3. hDisplay*vDisplay <= 1920*1088
 *                                                          4. 1<= vRefresh <= 120
 * 
 * @return 
 *         - \ref MTAPI_SUCCESS                  if custom presetting is successful.
 *         - \ref MTAPI_ERROR_UNKNOWN            if any unexpected error occurred.
 */
MtapiStatus MTAPI mtapiDisplayTryCustomDisplay(unsigned int displayId, MtapiCustomDisplay customDisplay);

/**
 * Saves custom resolutions on the specified display.
 *
 * For all products. 
 *
 * @param displayId                                [in]     The ID of the specified display.
 * @param customDisplay                            [in]     The custom display parameters passed in \ref mtapiDisplayTryCustomDisplay().
 * 
 * @return 
 *         - \ref MTAPI_SUCCESS                  if custom setting is saved successfully.
 *         - \ref MTAPI_ERROR_UNKNOWN            if any unexpected error occurred.
 */
MtapiStatus MTAPI mtapiDisplaySaveCustomDisplay(unsigned int displayId, MtapiCustomDisplay customDisplay);

/***********************************/
/** @}
 */
/***********************************/

#ifdef __cplusplus
}   // extern "C"
#endif

#endif