/* =========================================================================

  Program:   Multiple Projector Library
  Language:  C++
  Date:      $Date$
  Version:   $Revision$

  Copyright (c) 2013 Scalable Display Technologies, Inc.
  All Rights Reserved
  The source code contained herein is confidential and is considered a 
  trade secret of Scalable Display Technologies, Inc

===================================================================auto== */
// .NAME EasyBlendSDK - the API for the EasyBlend SDK
// .SECTION Description
// 
// The purpose of the EasyBlend SDK is to take an input rendered image
// and warp it using the calibration data generated by the EasyBlend
// calibration system.  
//
// The EasyBlend SDK provides a small set of functions that operate on an
// EasyBlendSDK_Mesh structure.  This structure is where all of the
// SDK state is stored.  This means that there can be multiple
// Mesh structures used in a single program.  Eash Mesh structure is
// initialized with data from a particular .ol or .pol mesh file ( generated
// by the EasyBlend calibration system ).
// 
// Before including EasyBlendSDK.h in your application, select the method or 
// graphics API that should be used to perform the warp by using a #define.
// Currently supported options include:
// EASYBLENDSDK_GRAPHICS_API_NONE (Data only mode, user provides warp implementation)
// EASYBLENDSDK_GRAPHICS_API_OGL  (OpenGL Core Profile)
// EASYBLENDSDK_GRAPHICS_API_DX12 (DX12)
// 
// By default, the SDK assumes that the data already resides in the back 
// buffer before the call to EasyBlendSDK_TransformInputToOutput, and that 
// the output of the calibration should be written back into the back buffer.
//
// The SDK methods all return errorcodes which should ALWAYS be checked.
// 
// .SECTION Usage
// 
// EasyBlendSDK_Mesh gMesh;
// err = EasyBlendSDK_Initialize( <mesh-ol-filename>, &gMesh, sdkmode )
// <check errorcode err>
// <set the view ( projection matrix ) based on gMesh>
// <Note: see example code for the SetView function>
// ....
// <in display loop, right before SwapBuffers>
// err = EasyBlendSDK_TransformInputToOutput( &gMesh )
// <check errorcode err>
// ....
// <at program exit>
// err = EayBlendSDK_Uninitialize( &gMesh )
// <check errorcode err>
// 

#ifndef _EasyBlendSDK_H_
#define _EasyBlendSDK_H_

#include <stdlib.h>
#include <vector>

#include "EasyBlendSDKPlatforms.h"

#include "EasyBlendSDKMesh.h"
#include "EasyBlendSDKErrors.h"

#ifdef EASYBLENDSDK_GRAPHICS_API_DX12
#include <d3d12.h>
#include <dxgi1_6.h>
#endif

#ifdef EASYBLENDSDK_GRAPHICS_API_VK
#include "VkRenderParameters.h"
#endif

// ============================================
// === Standard Functions that Everyone uses.
// ============================================

// Description:
// Initializes a Mesh structure from an EasyBlend calibration file
// (typically a .ol file or .pol file for dynamic eyepoint).  
// For OpenGL, this call MUST be made when a valid OpenGL context has been
// created. Otherwise the EasyBlend SDK will conclude that you only
// have OpenGL 1.0 support. The given Mesh pointer should be allocated
// ( not NULL ) and will be overwritten.
//
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_Initialize( const char* Filename,
                         EasyBlendSDK_Mesh* msm,
                         int SDKMode = EasyBlendSDK_SDKMODE_OpenGL,
                         EasyBlendSDKCallback cb = NULL,
                         void* cbData = NULL );


// Description:
// Given a correctly initialized SDK Mesh, releases the resources used
// by the Mesh structure.  The Mesh pointer memory must still be
// externally deallocated after this call.
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_Uninitialize( EasyBlendSDK_Mesh* msm,
                           EasyBlendSDKCallback cb = NULL,
                           void* cbData  = NULL );

// ============================================
// === OpenGL specific functionality.  
// === Use only with a mesh initialized using EasyBlendSDK_SDKMODE_OpenGL
// === Includes Functions For Optimizing Buffer/Texture use.
// === Setting an input buffer/texture removes a texture copy 
// === and improves performance.
// ============================================

#ifdef  EASYBLENDSDK_GRAPHICS_API_OGL

// Description:
// Takes an input rendered scene and warps it according to the given
// calibration mesh, rendering the output to an OpenGL buffer.
// The input and output locations must be set by calling the
// various SetInput* and SetOutput* EasyBlend SDK calls.  The
// Input and output default to both being the OpenGL BACK buffer.
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_TransformInputToOutputOGL(EasyBlendSDK_Mesh* msm);

// Description:
// Set the ReadBuffer to use as input for the SDK
// ( Defaults to GL_BACK )
// The given buffer MUST be the same resolution as the
// mesh ( given by the XRes and YRes fields ).
// If this is not the case, you must use a Texture as input
// and first render the data onto it.
EasyBlendSDK_API EasyBlendSDKError 
EasyBlendSDK_SetInputReadBuffer( EasyBlendSDK_Mesh* msm,
                                 EasyBlendSDKGLBuffer ReadBuffer );

// Description:
// Set a particular Texture as input to the SDK
EasyBlendSDK_API EasyBlendSDKError 
EasyBlendSDK_SetInputTexture2D( EasyBlendSDK_Mesh* msm,
                                EasyBlendSDKGLTexture Texture );

// Description:
// Set a rectangular sub-region of a Texture as input to the SDK
// Texture space goes from 0 -> 1 inclusive
//
// Parameters:
//    offsets and width/Height are in TEXTURE space ( so normalized to (0,1) range )
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetInputSubTexture2D( EasyBlendSDK_Mesh* msm,
                                   EasyBlendSDKGLTexture Texture, 
                                   double XOffset,
                                   double YOffset,
                                   double Width,
                                   double Height );

// Description:
// Set a rectangular subregion of an image loaded as a texture 
// as input to the SDK.
//
// Parameters:
//    ImageWidth and Height are the pixel resolution of the texture
//    PixelXOffset and PixelYOffset are in pixels
//    Width and Height are in pixels
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetInputSubImageTexture2D( EasyBlendSDK_Mesh* msm,
                                        EasyBlendSDKGLTexture Texture, 
                                        unsigned int ImageWidth,   
                                        unsigned int ImageHeight,
                                                 int PixelXOffset,
                                                 int PixelYOffset,
                                        unsigned int Width,        
                                        unsigned int Height );


// Description:
// Set a particular DrawBuffer as the output buffer for the SDK
// ( defaults to GL_BACK )
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetOutputDrawBuffer( EasyBlendSDK_Mesh* msm,
                                  EasyBlendSDKGLBuffer DrawBuffer );

// Description:
// Set a particular DrawBuffer as the output buffer for the SDK
// ( defaults to GL_BACK )
// 
// Parameters:
//     Width and Height are int PIXELS worth of output
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetOutputDrawSubBuffer( EasyBlendSDK_Mesh* msm,
                                     EasyBlendSDKGLBuffer DrawBuffer,
                                     int Width, int Height );

// Description:
// Set a particular DrawBuffer as the output buffer for the SDK
// ( defaults to GL_BACK )
// 
// Parameters:
//     Width and Height are int PIXELS worth of output
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetOutputDrawSubBufferWithOffset( EasyBlendSDK_Mesh* msm,
                                               EasyBlendSDKGLBuffer DrawBuffer,
                                               int Offsetx, int Offsety,
                                               int Width, int Height );
#endif

// ============================================
// === DX12 specific functionality.  
// === Use only with a mesh initialized using EasyBlendSDK_SDKMODE_DX12
// ============================================

#ifdef EASYBLENDSDK_GRAPHICS_API_DX12

// Description:
// Initialize the DX12 renderer
// 
// Parameters:
//     EasyBlend SDK mesh initialized using EasyBlendSDK_SDKMODE_DX12
//     D3D swap chain pointer
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_InitializeDX12_SwapChain( EasyBlendSDK_Mesh* msm, 
                                       IDXGISwapChain3* pSwapChain);

// Description:
// Fill a given command list with commands that will warp the image on the back buffer and
// write the warped image back into the same buffer.  The swap chain provided to
// EasyBlendSDK_InitializeDX12 will be used to obtain the current backbuffer resource.
// This resource will be assumed to be in the state D3D12_RESOURCE_STATE_PRESENT and will be
// returned to that state after executing the command list.  Caller is responsible for
// executing the command list on the appropriate command queue and then calling present.
// 
// This function should only be called if initialized with EasyBlendSDK_InitializeDX12_SwapChain
// 
// Parameters:
//     EasyBlend SDK mesh initialized using EasyBlendSDK_SDKMODE_DX12
//     D3D12 command list that is ready to accept commands
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_TransformInputToOutputDX12_SwapChain( EasyBlendSDK_Mesh* msm,
                                                   ID3D12GraphicsCommandList* pCmdList);

// Description:
// Initialize the DX12 renderer
// 
// Parameters:
//     EasyBlend SDK mesh initialized using EasyBlendSDK_SDKMODE_DX12
//     D3D12 device object pointer
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_InitializeDX12_Device( EasyBlendSDK_Mesh* msm,
                                    ID3D12Device* pDevice);

// Description:
// Fill a given command list with commands that will warp the provided image and
// write the warped image back into the provided rtv. The output resource will be 
// used to retrieve Width and Height for rendering. Caller is responsible for 
// executing the command list on the appropriate command queue and then calling present.
// 
// This function should only be called if initialized with EasyBlendSDK_InitializeDX12_Device
// 
// Parameters:
//     EasyBlend SDK mesh initialized using EasyBlendSDK_SDKMODE_DX12
//     ID3D12Resource pointer to the texture to be used as the source image
//     ID3D12Resource pointer to the output texture
//     D3D12_CPU_DESCRIPTOR_HANDLE destination rtv
//     ID3D12GraphicsCommandList pointer for command list to fill
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_TransformInputToOutputDX12_CommandList( EasyBlendSDK_Mesh* msm, 
                                                     ID3D12Resource* InputTexture, 
                                                     ID3D12Resource* OutputTexture, 
                                                     D3D12_CPU_DESCRIPTOR_HANDLE OutputRTV,
                                                     ID3D12GraphicsCommandList* pCommandList);

// Description:
// Initialize the DX12 renderer
// 
// Parameters:
//     EasyBlend SDK mesh initialized using EasyBlendSDK_SDKMODE_DX12
//     D3D12 command queue pointer that is of type D3D12_COMMAND_LIST_TYPE_DIRECT
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_InitializeDX12_CommandQueue( EasyBlendSDK_Mesh* msm,
                                          ID3D12CommandQueue* pCommandQueue);

// Description:
// Fill a command list created on the given command queue that will warp the provided image and
// write the warped image back into the provided rtv. The output resource will be 
// used to retrieve Width and Height for rendering, and a resource barrier will added to transition
// the output image to a final resource state of D3D12_RESOURCE_STATE_PRESENT. The filled command list 
// will then be executed on the given command queue. The resulting fence from executing the command list
// is not waited on.
// 
// This function should only be called if initialized with EasyBlendSDK_InitializeDX12_CommandQueue
// 
// Parameters:
//     EasyBlend SDK mesh initialized using EasyBlendSDK_SDKMODE_DX12
//     ID3D12Resource pointer to the texture to be used as the source image
//     ID3D12Resource pointer to the output texture
//     D3D12_CPU_DESCRIPTOR_HANDLE destination rtv
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_TransformInputToOutputDX12_CommandQueue( EasyBlendSDK_Mesh* msm,
                                                      ID3D12Resource* InputTexture,
                                                      ID3D12Resource* OutputTexture,
                                                      D3D12_CPU_DESCRIPTOR_HANDLE OutputRTV);

#endif

// ============================================
// === Vulkan specific functionality.  
// === Use only with a mesh initialized using EasyBlendSDK_SDKMODE_VK
// ============================================

#ifdef EASYBLENDSDK_GRAPHICS_API_VK
// Description:
// Initialize the Vulkan renderer
// 
// Parameters:
// 
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_InitializeVK(EasyBlendSDK_Mesh* msm, EasyBlendSDK_VK_InitializeParameters* initParameters);

// Description:
// 
// 
// Parameters:
// 
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_TransformInputToOutputVK(EasyBlendSDK_Mesh* msm, EasyBlendSDK_VK_RenderParameters* drawParameters);
#endif

// ============================================
// ========== Misc Functions
// ============================================

// Description:
// This command returns the view angles for the instance of the SDK.
// As Heading, then Pitch then Roll. The Angles are pre-computed in
// the SDK file, so that it only works with newer version of EasyBlend
// that write this information to disk. (Newer than Nov 2011 or newer)
EasyBlendSDK_API EasyBlendSDKError EasyBlendSDK_GetHeadingPitchRoll (
    double& rdDegreesHeading, double& rdDegreesPitch, double& rdDegreesRoll,
    EasyBlendSDK_Mesh* msm);

// Description:
// This command is used only for Dynamic Eyepoint. The new location of 
// the viewer is sent to the command, and a new frustum is calculated. 
// To use this function, the Initialize command must have been called
// with a .pol file. After this call, remember to get new frustum and
// use it to update the OpenGL frustum. This command is currently CPU
// bound.
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetEyepoint(EasyBlendSDK_Mesh* msm,
                         const double& eyeX,
                         const double& eyeY,
                         const double& eyeZ);

// Description:
// Set SDK profiling options. This call has no effect without
// a profiling build of the SDK.
//
// Parameters:
//     flags is a bitwise combination of the profiling flags defined
//     in EasyBlendSDKTypes.h.
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetProfilingFlags(EasyBlendSDK_Mesh* msm,
                               unsigned int flags);

// Description:
// Almost all users want the EasyBlend SDK to clear the output buffer
// before rendering to it. But, some specialized users need to turn it off.
// Please Call Initialize First(). Returns errors for NULL pointers or
// uninitialized pointers only.
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_SetClearOutputBeforeRendering(EasyBlendSDK_Mesh* msm,
                                           const bool &ShouldClear);
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_GetClearOutputBeforeRendering(EasyBlendSDK_Mesh* msm,
                                           bool &ShouldClear);


// Description:
// Should the eyepoint offset from the mesh file be used when rendering
// the scene?  Typically used for projection mapping scenarios.
EasyBlendSDK_API EasyBlendSDKError
EasyBlendSDK_GetUseEyepointOffset(EasyBlendSDK_Mesh* msm, bool &UseEyepointOffset);

// ============================================
// ========== Functions below are deprecated
// ============================================

// Description:
// Takes an input rendered scene and warps it according to the given
// calibration mesh, rendering the output to an OpenGL buffer.
// The input and output locations must be set by calling the
// various SetInput* and SetOutput* EasyBlend SDK calls.  The
// Input and output default to both being the OpenGL BACK buffer.
EasyBlendSDK_API EASYBLENDSDK_DEPRECATED_CALL(
  "EasyBlendSDK_TransformInputToOutput is deprecated, please use EasyBlendSDK_TransformInputToOutputOGL instead.",
  EasyBlendSDKError
  EasyBlendSDK_TransformInputToOutput(EasyBlendSDK_Mesh* msm)
);


// Description:
// This command sets the gamma.
EasyBlendSDK_API 
EASYBLENDSDK_DEPRECATED_CALL(
  "EasyBlendSDK_SetGamma is deprecated.",
  EasyBlendSDKError EasyBlendSDK_SetGamma(EasyBlendSDK_Mesh* msm, const float gamma,
  const int MaxAlpha)
);

// Description:
// Sets a lookup table to transform the current alpha channel
EasyBlendSDK_API
EASYBLENDSDK_DEPRECATED_CALL(
  "EasyBlendSDK_SetLookupTable is deprecated.",
  EasyBlendSDKError EasyBlendSDK_SetLookupTable(EasyBlendSDK_Mesh* msm, const std::vector<int>& lookup)
);

// Description:
// Set the texture sampling to be used during a call to
// TransformInputToOutput.  IMPORTANT: This is a debugging command to
// allow easy comparisons of sampling modes. Cubic filtering is only
// supported on graphics hardware and drivers that can handle GLSL
// shaders. On pre-GLSL hardware, the error UNSUPPORTED_IN_HARDWARE is
// returned.
EasyBlendSDK_API 
EASYBLENDSDK_DEPRECATED_CALL(
  "EasyBlendSDK_SetSampling is deprecated.",
  EasyBlendSDKError EasyBlendSDK_SetSampling(EasyBlendSDK_Mesh* msm,
  unsigned int sampling)
);

// Description:
// <DEPRECATED>
// Get the label identifying the mesh file.
EasyBlendSDK_API 
EASYBLENDSDK_DEPRECATED_CALL(
  "EasyBlendSDK_GetMeshLabel is deprecated.",
  EasyBlendSDKError EasyBlendSDK_GetMeshLabel(char Label[256], EasyBlendSDK_Mesh* msm)
);

// Description:
// <DEPRECATED>
// Please refer to EasyBlendSDK_Initialize call
EasyBlendSDK_API 
EASYBLENDSDK_DEPRECATED_CALL(
"Initialize is deprecated. Use EasyBlendSDK_Initialize instead.",
EasyBlendSDKError Initialize(const char* szFileName,
                             EasyBlendSDK_Mesh* msm)
);

// Description:
// <DEPRECATED>
// Please refer to EasyBlendSDK_Uninitialize call
EasyBlendSDK_API 
EASYBLENDSDK_DEPRECATED_CALL(
"UnInitialize is deprecated. Use EasyBlendSDK_UnInitialize instead.",
EasyBlendSDKError Uninitialize(EasyBlendSDK_Mesh* msm)
);

// Description:
// <DEPRECATED>
// Please refer to EasyBlendSDK_TransformInputToOutput call
EasyBlendSDK_API 
EASYBLENDSDK_DEPRECATED_CALL(
"OpenGLSwap is deprecated. Use EasyBlendSDK_TransformInputToOutput instead.",
EasyBlendSDKError OpenGLSwap(EasyBlendSDK_Mesh* msm)
);


// Description:
// <DEPRECATED>
// <NOT_IMPLEMENTED>
EasyBlendSDK_API EASYBLENDSDK_DEPRECATED_CALL(
"DirectXSwap sholud not be used in an OpenGL program at all.",
EasyBlendSDKError DirectXSwap(EasyBlendSDK_Mesh* msm)
);


#endif  /* ifndef _EasyBlendSDK_H_ */