OfxImageEffectOpenGLRenderSuiteV1
-
struct OfxImageEffectOpenGLRenderSuiteV1
OFX suite that provides image to texture conversion for OpenGL processing.
Public Members
-
OfxStatus (*clipLoadTexture)(OfxImageClipHandle clip, OfxTime time, const char *format, const OfxRectD *region, OfxPropertySetHandle *textureHandle)
loads an image from an OFX clip as a texture into OpenGL
clip
clip to load the image fromtime
effect time to load the image fromformat
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.region
region of the image to load (optional, set to NULL to get a ‘default’ region) this is in the CanonicalCoordinates.textureHandle
property set containing information about the texture
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.
Note
this is the OpenGL equivalent of clipGetImage from OfxImageEffectSuiteV1
- 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.
- Return:
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 plug-in 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 plug-in should abort the GL render and return kOfxStatErrMemory, after which the host can decide to retry the operation with CPU based processing.
-
OfxStatus (*clipFreeTexture)(OfxPropertySetHandle textureHandle)
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)
- Return:
kOfxStatOK - the image was successfully fetched and returned in the handle,
kOfxStatFailed - general failure for some reason,
kOfxStatErrBadHandle - the image handle was invalid,
-
OfxStatus (*flushResources)()
Request the host to minimize its GPU resource load.
When a plug-in 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 plug-in can try again to allocate resources which then might succeed if the host actually has released anything.
- Pre:
- Post:
No changes to the plug-in GL state should have been made.
- Return:
kOfxStatOK - the host has actually released some resources,
kOfxStatReplyDefault - nothing the host could do..
-
OfxStatus (*clipLoadTexture)(OfxImageClipHandle clip, OfxTime time, const char *format, const OfxRectD *region, OfxPropertySetHandle *textureHandle)
Properties for GPU rendering with other acceleration methods:
- group CudaRender
- Version
CUDA rendering was added in version 1.5.
Defines
-
kOfxImageEffectPropCudaRenderSupported
Indicates whether a host or plug-in can support CUDA render.
Type - string X 1
Property Set - plug-in descriptor (read/write), host descriptor (read only)
Default - “false” for a plug-in
Valid Values - This must be one of
”false” - the host or plug-in does not support CUDA render
”true” - the host or plug-in can support CUDA render
-
kOfxImageEffectPropCudaEnabled
Indicates that a plug-in SHOULD use CUDA render in the current action.
If a plug-in and host have both set kOfxImageEffectPropCudaRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as CUDA memory pointers.
Type - int X 1
Property Set - inArgs property set of the following actions…
Valid Values
0 indicates that the kOfxImagePropData of each image of each clip is a CPU memory pointer.
1 indicates that the kOfxImagePropData of each image of each clip is a CUDA memory pointer.
-
kOfxImageEffectPropCudaStreamSupported
Indicates whether a host or plug-in can support CUDA streams.
Type - string X 1
Property Set - plug-in descriptor (read/write), host descriptor (read only)
Default - “false” for a plug-in
Valid Values - This must be one of
”false” - in which case the host or plug-in does not support CUDA streams
”true” - which means a host or plug-in can support CUDA streams
-
kOfxImageEffectPropCudaStream
The CUDA stream to be used for rendering.
Type - pointer X 1
Property Set - inArgs property set of the following actions…
This property will only be set if the host and plug-in both support CUDA streams.
If set:
this property contains a pointer to the stream of CUDA render (cudaStream_t). In order to use it, reinterpret_cast<cudaStream_t>(pointer) is needed.
the plug-in SHOULD ensure that its render action enqueues any asynchronous CUDA operations onto the supplied queue.
the plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action, and SHOULD NOT call cudaDeviceSynchronize() at any time.
If not set:
the plug-in SHOULD ensure that any asynchronous operations it enqueues have completed before returning from the render action.
- group MetalRender
- Version
Metal rendering was added in version 1.5.
Defines
-
kOfxImageEffectPropMetalRenderSupported
Indicates whether a host or plug-in can support Metal render.
Type - string X 1
Property Set - plug-in descriptor (read/write), host descriptor (read only)
Default - “false” for a plug-in
Valid Values - This must be one of
”false” - the host or plug-in does not support Metal render
”true” - the host or plug-in can support Metal render
-
kOfxImageEffectPropMetalEnabled
Indicates that a plug-in SHOULD use Metal render in the current action.
If a plug-in and host have both set kOfxImageEffectPropMetalRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as Metal buffers.
Type - int X 1
Property Set - inArgs property set of the following actions…
Valid Values
0 indicates that the kOfxImagePropData of each image of each clip is a CPU memory pointer.
1 indicates that the kOfxImagePropData of each image of each clip is a Metal id<MTLBuffer>.
-
kOfxImageEffectPropMetalCommandQueue
The command queue of Metal render.
Type - pointer X 1
Property Set - inArgs property set of the following actions…
This property contains a pointer to the command queue to be used for Metal rendering (id<MTLCommandQueue>). In order to use it, reinterpret_cast<id<MTLCommandQueue>>(pointer) is needed.
The plug-in SHOULD ensure that its render action enqueues any asynchronous Metal operations onto the supplied queue.
The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.
- group OpenClRender
- Version
OpenCL rendering was added in version 1.5.
Defines
-
kOfxImageEffectPropOpenCLRenderSupported
Indicates whether a host or plug-in can support OpenCL Buffers render.
Type - string X 1
Property Set - plug-in descriptor (read/write), host descriptor (read only)
Default - “false” for a plug-in
Valid Values - This must be one of
”false” - the host or plug-in does not support OpenCL Buffers render
”true” - the host or plug-in can support OpenCL Buffers render
-
kOfxImageEffectPropOpenCLSupported
Indicates whether a host or plug-in can support OpenCL Images render.
Type - string X 1
Property Set - plug-in descriptor (read/write), host descriptor (read only)
Default - “false” for a plug-in
Valid Values - This must be one of
”false” - in which case the host or plug-in does not support OpenCL Images render
”true” - which means a host or plug-in can support OpenCL Images render
-
kOfxImageEffectPropOpenCLEnabled
Indicates that a plug-in SHOULD use OpenCL render in the current action.
If a plug-in and host have both set kOfxImageEffectPropOpenCLRenderSupported=”true” or have both set kOfxImageEffectPropOpenCLSupported=”true” then the host MAY set this property to indicate that it is passing images as OpenCL Buffers or Images.
When rendering using OpenCL Buffers, the cl_mem of the buffers are retrieved using kOfxImagePropData. When rendering using OpenCL Images, the cl_mem of the images are retrieved using kOfxImageEffectPropOpenCLImage. If both kOfxImageEffectPropOpenCLSupported (Buffers) and kOfxImageEffectPropOpenCLRenderSupported (Images) are enabled by the plug-in, it should use kOfxImageEffectPropOpenCLImage to determine which is being used by the host.
Type - int X 1
Property Set - inArgs property set of the following actions…
Valid Values
0 indicates that a plug-in SHOULD use OpenCL render in the render action
1 indicates that a plug-in SHOULD NOT use OpenCL render in the render action
-
kOfxImageEffectPropOpenCLCommandQueue
Indicates the OpenCL command queue that should be used for rendering.
Type - pointer X 1
Property Set - inArgs property set of the following actions…
This property contains a pointer to the command queue to be used for OpenCL rendering (cl_command_queue). In order to use it, reinterpret_cast<cl_command_queue>(pointer) is needed.
The plug-in SHOULD ensure that its render action enqueues any asynchronous OpenCL operations onto the supplied queue.
The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.
-
kOfxImageEffectPropOpenCLImage
Indicates the image handle of an image supplied as an OpenCL Image by the host.
Type - pointer X 1
Property Set - image handle returned by clipGetImage
This value should be cast to a cl_mem and used as the image handle when performing OpenCL Images operations. The property should be used (not kOfxImagePropData) when rendering with OpenCL Images (kOfxImageEffectPropOpenCLSupported), and should be used to determine whether Images or Buffers should be used if a plug-in supports both kOfxImageEffectPropOpenCLSupported and kOfxImageEffectPropOpenCLRenderSupported. Note: the kOfxImagePropRowBytes property is not required to be set by the host, since OpenCL Images do not have the concept of row bytes.
-
kOfxOpenCLProgramSuite
Typedefs
-
typedef struct OfxOpenCLProgramSuiteV1 OfxOpenCLProgramSuiteV1
OFX suite that allows a plug-in to get OpenCL programs compiled.
This is an optional suite the host can provide for building OpenCL programs for the plug-in, as an alternative to calling clCreateProgramWithSource / clBuildProgram. There are two advantages to doing this: The host can add flags (such as -cl-denorms-are-zero) to the build call, and may also cache program binaries for performance (however, if the source of the program or the OpenCL environment changes, the host must recompile so some mechanism such as hashing must be used).
-
struct OfxOpenCLProgramSuiteV1
- #include <ofxGPURender.h>
OFX suite that allows a plug-in to get OpenCL programs compiled.
This is an optional suite the host can provide for building OpenCL programs for the plug-in, as an alternative to calling clCreateProgramWithSource / clBuildProgram. There are two advantages to doing this: The host can add flags (such as -cl-denorms-are-zero) to the build call, and may also cache program binaries for performance (however, if the source of the program or the OpenCL environment changes, the host must recompile so some mechanism such as hashing must be used).
Public Members
-
OfxStatus (*compileProgram)(const char *pszProgramSource, int fOptional, void *pResult)
Compiles the OpenCL program.
-
OfxStatus (*compileProgram)(const char *pszProgramSource, int fOptional, void *pResult)