openfx-sys 0.1.0

#ifndef _ofxOpenGLRender_h_
#define _ofxOpenGLRender_h_


/*
Software License :

Copyright (c) 2010-15, The Open Effects Association Ltd. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    * Neither the name The Foundry Visionmongers Ltd, nor the names of its
      contributors may be used to endorse or promote products derived from this
      software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/


#ifdef __cplusplus
extern "C" {
#endif

/** @file ofxOpenGLRender.h

	This file contains an optional suite for performing OpenGL accelerated
	rendering of OpenFX Image Effect Plug-ins.  For details see
        \ref ofxOpenGLRender.
*/

/** @brief The name of the OpenGL render suite, used to fetch from a host
via OfxHost::fetchSuite
*/
#define kOfxOpenGLRenderSuite			"OfxImageEffectOpenGLRenderSuite"

//#define kOfxOpenGLRenderSuite_ext		"OfxImageEffectOpenGLRenderSuite_ext"


#ifndef kOfxBitDepthHalf
/** @brief String used to label the OpenGL half float (16 bit floating
point) sample format */
  #define kOfxBitDepthHalf "OfxBitDepthHalf"

#endif

/** @brief Indicates whether a host or plugin can support OpenGL accelerated
rendering

   - Type - C string X 1
   - Property Set - plugin descriptor (read/write), host descriptor (read
only) - plugin instance change (read/write)
   - Default - "false" for a plugin
   - Valid Values - This must be one of
     - "false"  - in which case the host or plugin does not support OpenGL
                  accelerated rendering
     - "true"   - which means a host or plugin can support OpenGL accelerated
                  rendering, in the case of plug-ins this also means that it
                  is capable of CPU based rendering in the absence of a GPU
     - "needed" - only for plug-ins, this means that an effect has to have
                  OpenGL support, without which it cannot work.

V1.4: It is now expected from host reporting v1.4 that the plugin can during instance change switch from true to false and false to true.

*/
#define kOfxImageEffectPropOpenGLRenderSupported "OfxImageEffectPropOpenGLRenderSupported"



/** @brief Indicates the bit depths supported by a plug-in during OpenGL renders.

    This is analogous to ::kOfxImageEffectPropSupportedPixelDepths. When a
    plug-in sets this property, the host will try to provide buffers/textures
    in one of the supported formats. Additionally, the target buffers where
    the plug-in renders to will be set to one of the supported formats.

    Unlike ::kOfxImageEffectPropSupportedPixelDepths, this property is
    optional. Shader-based effects might not really care about any
    format specifics when using OpenGL textures, so they can leave this unset
    and allow the host the decide the format.


   - Type - string X N
   - Property Set - plugin descriptor (read only)
   - Default - none set
   - Valid Values - This must be one of
       - ::kOfxBitDepthNone (implying a clip is unconnected, not valid for an
         image)
       - ::kOfxBitDepthByte
       - ::kOfxBitDepthShort
       - ::kOfxBitDepthHalf
       - ::kOfxBitDepthFloat
*/
#define kOfxOpenGLPropPixelDepth "OfxOpenGLPropPixelDepth"



/** @brief Indicates that an image effect SHOULD use OpenGL acceleration in
the current action

   When a plugin and host have established they can both use OpenGL renders
   then when this property has been set the host expects the plugin to render
   its result into the buffer it has setup before calling the render.  The
   plugin can then also safely use the 'OfxImageEffectOpenGLRenderSuite'

   - Type - int X 1
   - Property Set - inArgs property set of the following actions...
      - ::kOfxImageEffectActionRender
      - ::kOfxImageEffectActionBeginSequenceRender
      - ::kOfxImageEffectActionEndSequenceRender
   - Valid Values
      - 0 indicates that the effect cannot use the OpenGL suite
      - 1 indicates that the effect should render into the texture,
        and may use the OpenGL suite functions.

\note Once this property is set, the host and plug-in have agreed to
use OpenGL, so the effect SHOULD access all its images through the
OpenGL suite.

v1.4:  kOfxImageEffectPropOpenGLEnabled should probably be checked in Instance Changed prior to try to read image via clipLoadTexture

*/
#define kOfxImageEffectPropOpenGLEnabled "OfxImageEffectPropOpenGLEnabled"



/** @brief Indicates the texture index of an image turned into an OpenGL
texture by the host

   - Type - int X 1
   - Property Set - texture handle returned by
`        OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture (read only)

	This value should be cast to a GLuint and used as the texture index when
        performing OpenGL texture operations.

   The property set of the following actions should contain this property:
      - ::kOfxImageEffectActionRender
      - ::kOfxImageEffectActionBeginSequenceRender
      - ::kOfxImageEffectActionEndSequenceRender
*/
#define kOfxImageEffectPropOpenGLTextureIndex "OfxImageEffectPropOpenGLTextureIndex"



/** @brief Indicates the texture target enumerator of an image turned into
    an OpenGL texture by the host

   - Type - int X 1
   - Property Set - texture handle returned by
        OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture (read only)
	This value should be cast to a GLenum and used as the texture target
	when performing OpenGL texture operations.

   The property set of the following actions should contain this property:
      - ::kOfxImageEffectActionRender
      - ::kOfxImageEffectActionBeginSequenceRender
      - ::kOfxImageEffectActionEndSequenceRender
*/
#define kOfxImageEffectPropOpenGLTextureTarget "OfxImageEffectPropOpenGLTextureTarget"



/** @name StatusReturnValues
OfxStatus returns indicating that a OpenGL render error has occurred:

 - If a plug-in returns ::kOfxStatGLRenderFailed, the host should retry the
   render with OpenGL rendering disabled.

 - If a plug-in returns ::kOfxStatGLOutOfMemory, the host may choose to free
   resources on the GPU and retry the OpenGL render, rather than immediately
   falling back to CPU rendering.
 */
/** @{ */
/** @brief render ran out of memory */
#define kOfxStatGLOutOfMemory  ((int) 1001)

/** @brief render failed in a non-memory-related way */
#define kOfxStatGLRenderFailed ((int) 1002)

/** @} */

/** @brief OFX suite that provides image to texture conversion for OpenGL
    processing
 */

typedef struct OfxImageEffectOpenGLRenderSuiteV1
{
  /** @brief loads an image from an OFX clip as a texture into OpenGL

      \arg clip   - the clip to load the image from
      \arg time   - effect time to load the image from
      \arg format - the requested texture format (As in
            none,byte,word,half,float, etc..)
            When set to NULL, the host decides the format based on the
	    plug-in's ::kOfxOpenGLPropPixelDepth setting.
      \arg region - region of the image to load (optional, set to NULL to
            get a 'default' region)
	    this is in the \ref CanonicalCoordinates.
      \arg textureHandle - a property set containing information about the
            texture

  An image is fetched from a clip at the indicated time for the given region
  and loaded into an OpenGL texture. When a specific format is requested, the
  host ensures it gives the requested format.
  When the clip specified is the "Output" clip, the format is ignored and
  the host must bind the resulting texture as the current color buffer
  (render target). This may also be done prior to calling the
  ::kOfxImageEffectActionRender action.
  If the \em region parameter is set to non-NULL, then it will be clipped to
  the clip's Region of Definition for the given time.
  The returned image will be \em at \em least as big as this region.
  If the region parameter is not set or is NULL, then the region fetched will be at
  least the Region of Interest the effect has previously specified, clipped to
  the clip's Region of Definition.
  Information about the texture, including the texture index, is returned in
  the \em textureHandle argument.
  The properties on this handle will be...
    - ::kOfxImageEffectPropOpenGLTextureIndex
    - ::kOfxImageEffectPropOpenGLTextureTarget
    - ::kOfxImageEffectPropPixelDepth
    - ::kOfxImageEffectPropComponents
    - ::kOfxImageEffectPropPreMultiplication
    - ::kOfxImageEffectPropRenderScale
    - ::kOfxImagePropPixelAspectRatio
    - ::kOfxImagePropBounds
    - ::kOfxImagePropRegionOfDefinition
    - ::kOfxImagePropRowBytes
    - ::kOfxImagePropField
    - ::kOfxImagePropUniqueIdentifier

  With the exception of the OpenGL specifics, these properties are the same
  as the properties in an image handle returned by clipGetImage in the image
  effect suite.
\pre
 - clip was returned by clipGetHandle
 - Format property in the texture handle

\post
 - texture handle to be disposed of by clipFreeTexture before the action
returns
 - when the clip specified is the "Output" clip, the format is ignored and
   the host must bind the resulting texture as the current color buffer
   (render target).
   This may also be done prior to calling the render action.

@returns
  - ::kOfxStatOK           - the image was successfully fetched and returned
                             in the handle,
  - ::kOfxStatFailed       - the image could not be fetched because it does
                             not exist in the clip at the indicated
                             time and/or region, the plugin should continue
                             operation, but assume the image was black and
			     transparent.
  - ::kOfxStatErrBadHandle - the clip handle was invalid,
  - ::kOfxStatErrMemory    - not enough OpenGL memory was available for the
                             effect to load the texture.
                             The plugin should abort the GL render and
			     return ::kOfxStatErrMemory, after which the host can
			     decide to retry the operation with CPU based processing.

\note
  - this is the OpenGL equivalent of clipGetImage from OfxImageEffectSuiteV1


*/

  OfxStatus (*clipLoadTexture)(OfxImageClipHandle clip,
                               OfxTime       time,
                               const char   *format,
                               const OfxRectD     *region,
                               OfxPropertySetHandle   *textureHandle);

  /** @brief Releases the texture handle previously returned by
clipLoadTexture

  For input clips, this also deletes the texture from OpenGL.
  This should also be called on the output clip; for the Output
  clip, it just releases the handle but does not delete the
  texture (since the host will need to read it).

  \pre
    - textureHandle was returned by clipGetImage

  \post
    - all operations on textureHandle will be invalid, and the OpenGL texture
      it referred to has been deleted (for source clips)

  @returns
    - ::kOfxStatOK - the image was successfully fetched and returned in the
         handle,
    - ::kOfxStatFailed - general failure for some reason,
    - ::kOfxStatErrBadHandle - the image handle was invalid,
*/
  OfxStatus (*clipFreeTexture)(OfxPropertySetHandle   textureHandle);


  /** @brief Request the host to minimize its GPU resource load

  When a plugin fails to allocate GPU resources, it can call this function to
  request the host to flush its GPU resources if it holds any.
  After the function the plugin can try again to allocate resources which then
  might succeed if the host actually has released anything.

  \pre
  \post
    - No changes to the plugin GL state should have been made.

  @returns
    - ::kOfxStatOK           - the host has actually released some
resources,
    - ::kOfxStatReplyDefault - nothing the host could do..
 */
  OfxStatus (*flushResources)( );

} OfxImageEffectOpenGLRenderSuiteV1;


/** @brief Action called when an effect has just been attached to an OpenGL
context.

The purpose of this action is to allow a plugin to set up any data it may need
to do OpenGL rendering in an instance. For example...
   - allocate a lookup table on a GPU,
   - create an openCL or CUDA context that is bound to the host's OpenGL
     context so it can share buffers.

The plugin will be responsible for deallocating any such shared resource in the
\ref ::kOfxActionOpenGLContextDetached action.

A host cannot call ::kOfxActionOpenGLContextAttached on the same instance
without an intervening ::kOfxActionOpenGLContextDetached. A host can have a
plugin swap OpenGL contexts by issuing a attach/detach for the first context
then another attach for the next context.

The arguments to the action are...
  \arg handle - handle to the plug-in instance, cast to an
  \ref OfxImageEffectHandle
  \arg inArgs - is redundant and set to null
  \arg outArgs - is redundant and set to null

A plugin can return...
  - ::kOfxStatOK, the action was trapped and all was well
  - ::kOfxStatReplyDefault, the action was ignored, but all was well anyway
  - ::kOfxStatErrMemory, in which case this may be called again after a memory
    purge
  - ::kOfxStatFailed, something went wrong, but no error code appropriate,
    the plugin should to post a message if possible and the host should not
    attempt to run the plugin in OpenGL render mode.
*/
#define kOfxActionOpenGLContextAttached "OfxActionOpenGLContextAttached"


/** @brief Action called when an effect is about to be detached from an
OpenGL context

The purpose of this action is to allow a plugin to deallocate any resource
allocated in \ref ::kOfxActionOpenGLContextAttached just before the host
decouples a plugin from an OpenGL context.
The host must call this with the same OpenGL context active as it
called with the corresponding ::kOfxActionOpenGLContextAttached.

The arguments to the action are...
  \arg handle - handle to the plug-in instance, cast to an
  \ref OfxImageEffectHandle
  \arg inArgs - is redundant and set to null
  \arg outArgs - is redundant and set to null

A plugin can return...
  - ::kOfxStatOK, the action was trapped and all was well
  - ::kOfxStatReplyDefault, the action was ignored, but all was well anyway
  - ::kOfxStatErrMemory, in which case this may be called again after a memory
    purge
  - ::kOfxStatFailed, something went wrong, but no error code appropriate,
    the plugin should to post a message if possible and the host should not
    attempt to run the plugin in OpenGL render mode.
*/
#define kOfxActionOpenGLContextDetached "kOfxActionOpenGLContextDetached"



/** @page ofxOpenGLRender OpenGL Acceleration of Rendering

@section ofxOpenGLRenderIntro Introduction

The OfxOpenGLRenderSuite allows image effects to use OpenGL commands
(hopefully backed by a GPU) to accelerate rendering
of their outputs. The basic scheme is simple....
  - An effect indicates it wants to use OpenGL acceleration by setting the
    ::kOfxImageEffectPropOpenGLRenderSupported flag on its descriptor
  - A host indicates it supports OpenGL acceleration by setting
    ::kOfxImageEffectPropOpenGLRenderSupported on its descriptor
  - In an effect's ::kOfxImageEffectActionGetClipPreferences action, an
    effect indicates what clips it will be loading images from onto the GPU's
    memory during an effect's ::kOfxImageEffectActionRender action.

@section ofxOpenGLRenderHouseKeeping OpenGL House Keeping

If a host supports OpenGL rendering then it flags this with the string
property ::kOfxImageEffectPropOpenGLRenderSupported on its descriptor property
set. Effects that cannot run without OpenGL support should examine this in
::kOfxActionDescribe action and return a ::kOfxStatErrMissingHostFeature
status flag if it is not set to "true".

Effects flag to a host that they support OpenGL rendering by setting the
string property ::kOfxImageEffectPropOpenGLRenderSupported on their effect
descriptor during the ::kOfxActionDescribe action. Effects can work in three
ways....
  - purely on CPUs without any OpenGL support at all, in which case they
    should set ::kOfxImageEffectPropOpenGLRenderSupported to be "false" (the
    default),
  - on CPUs but with optional OpenGL support, in which case they should set
    ::kOfxImageEffectPropOpenGLRenderSupported to be "true",
  - only with OpenGL support, in which case they should set
    ::kOfxImageEffectPropOpenGLRenderSupported to be "needed".

Hosts can examine this flag and respond to it appropriately.

Effects can use OpenGL accelerated rendering during the following
action...
  - ::kOfxImageEffectActionRender

If an effect has indicated that it optionally supports OpenGL acceleration,
it should check the property ::kOfxImageEffectPropOpenGLEnabled
passed as an in argument to the following actions,
  - ::kOfxImageEffectActionRender
  - ::kOfxImageEffectActionBeginSequenceRender
  - ::kOfxImageEffectActionEndSequenceRender

If this property is set to 0, then it should not attempt to use any calls to
the OpenGL suite or OpenGL calls whilst rendering.


@section ofxOpenGLRenderGettingTextures Getting Images as Textures

An effect could fetch an image into memory from a host via the standard
Image Effect suite "clipGetImage" call, then create an OpenGL
texture from that. However as several buffer copies and various other bits
of house keeping may need to happen to do this, it is more
efficient for a host to create the texture directly.

The OfxOpenGLRenderSuiteV1::clipLoadTexture function does this. The
arguments and semantics are similar to the
OfxImageEffectSuiteV2::clipGetImage function, with a few minor changes.

The effect is passed back a property handle describing the texture. Once the
texture is finished with, this should be disposed
of via the OfxOpenGLRenderSuiteV1::clipFreeTexture function, which will also
delete the associated OpenGL texture (for source clips).

The returned handle has a set of properties on it, analogous to the
properties returned on the image handle by
OfxImageEffectSuiteV2::clipGetImage. These are:
    - ::kOfxImageEffectPropOpenGLTextureIndex
    - ::kOfxImageEffectPropOpenGLTextureTarget
    - ::kOfxImageEffectPropPixelDepth
    - ::kOfxImageEffectPropComponents
    - ::kOfxImageEffectPropPreMultiplication
    - ::kOfxImageEffectPropRenderScale
    - ::kOfxImagePropPixelAspectRatio
    - ::kOfxImagePropBounds
    - ::kOfxImagePropRegionOfDefinition
    - ::kOfxImagePropRowBytes
    - ::kOfxImagePropField
    - ::kOfxImagePropUniqueIdentifier

The main difference between this and an image handle is that the
::kOfxImagePropData property is replaced by the
kOfxImageEffectPropOpenGLTextureIndex property.
This integer property should be cast to a GLuint and is the index to use for
the OpenGL texture.
Next to texture handle the texture target enumerator is given in
kOfxImageEffectPropOpenGLTextureTarget

Note, because the image is being directly loaded into a texture by the host
it need not obey the Clip Preferences action to remap the image to the pixel
depth the effect requested.

@section ofxOpenGLRenderOutput Render Output Directly with OpenGL

Effects can use the graphics context as they see fit. They may be doing
several render passes with fetch back from the card to main memory
via 'render to texture' mechanisms interleaved with passes performed on the
CPU. The effect must leave output on the graphics card in the provided output
image texture buffer.

The host will create a default OpenGL viewport that is the size of the
render window passed to the render action. The following
code snippet shows how the viewport should be rooted at the bottom left of
the output texture.

\verbatim
  // set up the OpenGL context for the render to texture
  ...

  // figure the size of the render window
  int dx = renderWindow.x2 - renderWindow.x1;
  int dy = renderWindow.y2 - renderWindow.y2;

  // setup the output viewport
  glViewport(0, 0, dx, dy);

\endverbatim

Prior to calling the render action the host may also choose to
bind the output texture as the current color buffer (render target), or they
may defer doing this until clipLoadTexture is called for the output clip.

After this, it is completely up to the effect to choose what OpenGL
operations to render with, including projections and so on.

@section ofxOpenGLRenderContext OpenGL Current Context

The host is only required to make the OpenGL context current (e.g.,
using wglMakeCurrent, for Windows) during the following actions:

   - ::kOfxImageEffectActionRender
   - ::kOfxImageEffectActionBeginSequenceRender
   - ::kOfxImageEffectActionEndSequenceRender
   - ::kOfxActionOpenGLContextAttached
   - ::kOfxActionOpenGLContextDetached

For the first 3 actions, Render through EndSequenceRender, the host is only
required to set the OpenGL context if ::kOfxImageEffectPropOpenGLEnabled is
set.  In other words, a plug-in should not expect the OpenGL context to be
current for other OFX calls, such as ::kOfxImageEffectActionDescribeInContext.

*/

#ifdef __cplusplus
}
#endif


#endif