481 lines
19 KiB
C++
481 lines
19 KiB
C++
/* =========================================================================
|
|
|
|
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_ */
|
|
|