Suites

Suites

For information on how to acquire and manage suites, see SweetPea Suites.

---

Export File Suite

A cross-platform suite for writing to files on disk. Also provides a call to get the file path, given the file object.

Version 2 resolves a mismatch in seek modes in version 1, where fileSeekMode_End was handled as fileSeekMode_Current and visa versa.

See PrSDKExportFileSuite.h.

---

Export Info Suite

GetExportSourceInfo

Get information on the source currently being exported.

prSuiteError (*GetExportSourceInfo)(
  csSDK_uint32                inExporterPluginID,
  PrExportSourceInfoSelector  inSelector,
  PrParam                     *outSourceInfo);

Value	Type	Description
kExportInfo_VideoWidth	Int32	Width of source video
kExportInfo_VideoHeight	Int32	Height of source video
kExportInfo_VideoFrameRate	PrTime	Frame rate
kExportInfo_VideoFieldType	Int32	One of the prFieldType values
kExportInfo_VideoDuration	Int64	A PrTime value
kExportInfo_PixelAspectNumerator	Int32	Pixel aspect ratio (PAR) numerator
kExportInfo_PixelAspectDenominator	Int32	Pixel aspect ratio denominator
kExportInfo_AudioDuration	Int64	A PrTime value
kExportInfo_AudioChannelsType	Int32	One of the PrAudioChannelType values.
		Returns 0 (which is undefined) if there’s no audio.
kExportInfo_AudioSampleRate	Float64
kExportInfo_SourceHasAudio	Bool	Non-zero if source has audio
kExportInfo_SourceHasVideo	Bool	Non-zero if source has video
kExportInfo_RenderAsPreview	Bool	Returns a non-zero value if currently rendering preview files.
kExportInfo_SequenceGUID	Guid	A PrPluginID, which is a unique GUID for the sequence.
kExportInfo_SessionFilePath	PrMemoryPtr	A prUTF16Char array. The exporter should release the pointer using the Memory Manager Suite.
kExportInfo_VideoPosterFrameTickTime	Int64	New in CS5. A PrTime value.
kExportInfo_SourceTimecode	PrMemoryPtr	New in CS5.0.2. The timecode of the source clip or sequence.
		The sequence timecode is set by the Start Time of a sequence using the sequence wing-menu. A pointer to a ExporterTimecodeRec structure.
		The exporter should release the pointer using the Memory Manager Suite.
kExportInfo_UsePreviewFiles	Bool	New in CC. Use this to check if the user has checked “Use Previews” in the Export Settings dialog.
		If so, if possible, reuse any preview files already rendered, which can be retrieved using AcquireVideoSegmentsWithPreviewsID in the Video Segment Suite.
kExportInfo_NumAudioChannels	Int32	New in CC. Get the number of audio channels in a given source.
		This can be used to automatically initialize the audio channel parameter in the Audio tab of the Export Settings to match the source.

typedef struct {
  csSDK_int64  mTimecodeTicks;
  csSDK_int64  mTicksPerFrame;
  bool         mTimecodeStartPrefersDropFrame;
} ExporterTimecodeRec;

---

Export Param Suite

Specify all parameters for your exporter UI. See PrSDKExportParamSuite.h.

Also, see the SDK Export sample for a demonstration of how to use this suite.

To provide either a set of radio buttons or a drop-down list of choices, use AddConstrainedValuePair().

Adding two choices will result in a pair of radio buttons side-by-side.

Three or more choices will be displayed as a drop-down box.

Adding only one value will result in a hard-coded string.

In CS5, and later fixed in 5.0.2, there is an issue where width and height ranges aren’t correctly set.

You may notice this when adjusting the width and height in the Export Settings UI.

By unclicking the chain that constrains width and height ratio, you will be able to modify the width and height.

As a side-effect of this bug, if the exporter is used to render preview files in an Editing Mode, the user will be able to choose any preview frame size between 24x24 and 10240x8192.

CS6 adds SetParamDescription(), to set tooltip strings for parameters.

CC adds MoveParam(), to move an existing parameter to a new location. This can be used for both standard parameters and group parameters.

---

Export Progress Suite

For pull-model exporters. Report progress during the export. Also, handle the case where the user pauses or cancels an export. See PrSDKExportProgressSuite.h.

---

Export Standard Param Suite

New in CS6. A suite for registering one of several common parameter sets, reducing parameter management code on the plugin side.

AddStandardParams

Register a set of standard parameters to be used by the exporter.

Call during exSelGenerateDefaultParams.

prSuiteError (*AddStandardParams)(
  csSDK_uint32       inExporterID,
  PrSDKStdParamType  inSDKStdParamType);

Member	Description
inExporterID	Pass in exporterPluginID from exDoExportRec.
inSDKStdParamType	Use one of the following:
	enum PrSDKStdParamType { SDKStdParams_Video, SDKStdParams_Audio, SDKStdParams_Still, SDKStdParams_VideoBitrateGroup, SDKStdParams_Video_NoRenderMax, SDKStdParams_Video_AddRenderMax, SDKStdParams_AudioTabOnly, SDKStdParams_AudioBitrateGroup, SDKStdParams_VideoWithSizePopup };

PostProcessParamNames

Call during exSelPostProcessParams.

prSuiteError (*PostProcessParamNames)(
  csSDK_uint32        inExporterID,
  PrAudioChannelType  inSourceAudioChannelType);

Member	Description
inExporterID	Pass in exporterPluginID from exDoExportRec.
inSourceAudioChannelType	Pass in the source audio channel type, which can be queried from GetExportSourceInfo in the Export Info Suite.

QueryOutputSettings

Call during exSelQueryOutputSettings.

prSuiteError (*QueryOutputSettings)(
  csSDK_uint32               inExporterID,
  exQueryOutputSettingsRec*  outOutputSettings);

Member	Description
inExporterID	Pass in exporterPluginID from exDoExportRec.
outOutputSettings	This structure will be filled out based on the standard parameter settings.

MakeParamSummary

Call during exSelGetParamSummary.

prSuiteError (*MakeParamSummary)(
  csSDK_uint32  inExporterID,
  csSDK_int32   inDoVideo,
  csSDK_int32   inDoAudio,
  prUTF16Char*  outVideoDescription,
  prUTF16Char*  outAudioDescription);

Member	Description
inExporterID	Pass in exporterPluginID from exDoExportRec.
inDoVideo	Pass in exParamSummaryRec.exportVideo / exportAudio so that the summary will be set based on whether video / audio are being exported.
inDoAudio
outVideoDescription	These will be filled out based on the standard parameter settings.
outAudioDescription

---

Exporter Utility Suite

New in CS6. Provides functions for push-model exporters, and also provides a way to register an export event (error, warning, or info) to be displayed by the host and written to the log.

DoMultiPassExportLoop

Register the callback to be made to push video frames to the exporter. This function assumes that your exporter supports exSelQueryOutputSettings, which will be called.

prSuiteError (*DoMultiPassExportLoop)(
  csSDK_uint32                                     inExporterID,
  const ExportLoopRenderParams*                    inRenderParams,
  csSDK_uint32                                     inNumberOfPasses,
  PrSDKMultipassExportLoopFrameCompletionFunction  inCompletionFunction,
  void*                                            inCompletionParam);

Member	Description
inExporterID	Pass in exporterPluginID from exDoExportRec.
inRenderParams	Pass in the parameters that will be used for the render loop that will push rendered frames via the provided callback inCompletionFunction.
	inReservedProgressPreRender and inReservedProgressPostRender should be set to the amount of progress to be shown in any progress bar before starting the render loop, and how much is remaining after finishing the render loop.
	These values default to zero.
	typedef struct { csSDK_int32 inRenderParamsSize; csSDK_int32 inRenderParamsVersion; PrPixelFormat inFinalPixelFormat; PrTime inStartTime; PrTime inEndTime; float inReservedProgressPreRender; float inReservedProgressPostRender; bool inHardwareResidentFrameOutputSupported; // new in 14.x } ExportLoopRenderParams;
inNumberOfPasses	Set to 1, unless you need multipass encoding such as two-pass or three-pass encoding.
inCompletionFunction	Provide your own callback here, which will be called when the host pushes rendered frames. Use the following function signature:
	typedef prSuiteError (*PrSDKMultipassExportLoop FrameCompletionFunction)( csSDK_uint32 inWhichPass, csSDK_uint32 inFrameNumber, csSDK_uint32 inFrameRepeatCount, PPixHand inRenderedFrame, void* inCallbackData);
	Currently, there is no simple way to ensure that pushed frames survive longer than the life of the function call.
	If you are interested in this capability, please contact us and explain your need.
inCompletionParam	Pass in a void * to the data you wish to send to your inCompletionFunction above in inCallbackData.

ReportIntermediateProgressForRepeatedVideoFrame

Register the callback to be made to push video frames to the exporter.

This function assumes that your exporter supports exSelQueryOutputSettings, which will be called.

prSuiteError (*ReportIntermediateProgressForRepeatedVideoFrame)(
  csSDK_uint32  inExporterID,
  csSDK_uint32  inRepetitionsProcessedSinceLastUpdate);

Member	Description
inExporterID	Pass in exporterPluginID from exDoExportRec.
inRepetitionsProcessedSinceLastUpdate	Pass in the number of repeated frames processed since the last call was made, if any.

ReportEvent

Report an event to the host, for a specific encode in progress in the Adobe Media Encoder render queue or Premiere Pro.

These events are displayed in the application UI, and are also added to the AME encoding log.

prSuiteError (*ReportEvent)(
  csSDK_uint32        inExporterID,
  csSDK_uint32        inEventType,
  const prUTF16Char*  inEventTitle,
  const prUTF16Char*  inEventDescription);

Member	Description
inExporterID	Pass in exporterPluginID from exDoExportRec.
inEventType	Use one of the types from the Error Suite:
	- kEventTypeInformational
	- kEventTypeWarning
	- kEventTypeError
inEventTitle	Provide information about the event for the user.
inEventDescription

---

Palette Suite

A seldom-used suite for palettizing an image, for example, for GIFs. See PrSDKPaletteSuite.h.

---

Sequence Audio Suite

Get audio from the host.

MakeAudioRenderer

Create an audio renderer, in preparation to get rendered audio from the host.

prSuiteError (*MakeAudioRenderer)(
  csSDK_uint32        inPluginID,
  PrTime              inStartTime,
  PrAudioChannelType  inChannelType,
  PrAudioSampleType   inSampleType,
  float               inSampleRate,
  csSDK_uint32*       outAudioRenderID);

Member	Description
inPluginID	Pass in exporterPluginID from exDoExportRec.
inStartTime	Start time for the audio requests.
inChannelType	PrAudioChannelType enum value for the channel type needed.
inSampleType	This should always be kPrAudioSampleType_32BitFloat. Other types are unsupported.
inSampleRate	Samples per second.
outAudioRenderID	This ID passed back is needed for subsequent calls to this suite.

ReleaseAudioRenderer

Release the audio renderer when the exporter is done requesting audio.

prSuiteError (*ReleaseAudioRenderer)(
  csSDK_uint32  inPluginID,
  csSDK_uint32  inAudioRenderID);

Member	Description
inPluginID	Pass in exporterPluginID from exDoExportRec.
inAudioRenderID	The call will release the audio renderer with this ID.

GetAudio

Returns from the host the next contiguous requested number of audio sample frames, specified in inFrameCount, in inBuffer as arrays of uninterleaved floating point values.

Returns suiteError_NoError if no error.

The plugin must manage the memory allocation of inBuffer, which must point to n buffers of floating point values of length inFrameCount, where n is the number of channels.

When inClipAudio is non-zero, this parameter makes GetAudio clip the audio samples at +/- 1.0.

prSuiteError (*GetAudio)(
  csSDK_uint32  inAudioRenderID,
  csSDK_uint32  inFrameCount,
  float**       inBuffer,
  char          inClipAudio);

Member	Description
inAudioRenderID	Pass in the outAudioRenderID returned from MakeAudioRenderer().
	This gives the host the context of the audio render.
inFrameCount	The number of audio frames to return in inBuffer.
	The next contiguous audio frames will always be returned, unless ResetAudioToBeginning has just been called.
inBuffer	An array of float arrays, allocated by the exporter.
	The host returns the samples for each audio channel in a separate array.
inClipAudio	When true, GetAudio will return audio clipped at +/- 1.0. Otherwise, it will return unclipped audio.

ResetAudioToBeginning

This call will reset the position on the audio generation to time zero. This can be used for multipass encoding.

prSuiteError (*ResetAudioToBeginning)(
  csSDK_uint32  inAudioRenderID);

GetMaxBlip

Returns the maximum number of audio sample frames that can be requested from one call to GetAudio in maxBlipSize.

prSuiteError (*GetMaxBlip)(
  csSDK_uint32  inAudioRenderID,
  PrTime        inTicksPerFrame,
  csSDK_uint32*  maxBlipSize);

---

Sequence Render Suite

Get rendered video from one of the renderers available to the host. This may use one of the host’s built-in renderers, or a plugin renderer, if available For best performance, use the asynchronous render requests with the source media prefetching calls, although synchronous rendering is available too.

Version 4, new in CS5.5, adds RenderVideoFrameAndConformToPixelFormat().

MakeVideoRenderer()

Create a video renderer, in preparation to get rendered video.

prSuiteError (*MakeVideoRenderer)(
  csSDK_uint32   pluginID,
  csSDK_uint32*  outVideoRenderID
  PrTime         inFrameRate);

Member	Description
pluginID	Pass in exporterPluginID from exDoExportRec.
outVideoRenderID	This ID passed back is needed for subsequent calls to this suite.
inFrameRate	Frame rate, in ticks.

ReleaseVideoRenderer()

Release the video renderer when the exporter is done requesting video.

prSuiteError (*ReleaseVideoRenderer)(
  csSDK_uint32  pluginID,
  csSDK_uint32  inVideoRenderID);

Member	Description
pluginID	Pass in exporterPluginID from exDoExportRec.
inVideoRenderID	The call will release the video renderer with this ID.

struct SequenceRender_ParamsRec

Fill this structure in before calling RenderVideoFrame(), QueueAsyncVideoFrameRender(), or PrefetchMediaWithRenderParameters().

Note

If the frame aspect ratio of the request does not match that of the sequence, the frame will be letterboxed or pillarboxed, rather than stretched to fit the frame.

typedef struct {
  const PrPixelFormat*  inRequestedPixelFormatArray;
  csSDK_int32           inRequestedPixelFormatArrayCount;
  csSDK_int32           inWidth;
  csSDK_int32           inHeight;
  csSDK_int32           inPixelAspectRatioNumerator;
  csSDK_int32           inPixelAspectRatioDenominator;
  PrRenderQuality       inRenderQuality;
  prFieldType           inFieldType;
  csSDK_int32           inDeinterlace;
  PrRenderQuality       inDeinterlaceQuality;
  csSDK_int32           inCompositeOnBlack;
} SequenceRender_ParamsRec;

Member	Description
inRequestedPixelFormatArray	An array of PrPixelFormats that list your format preferences in order.
inRequestedPixelFormatArrayCount	Size of the pixel format array.
inWidth	Width to render at.
inHeight	Height to render at.
inPixelAspectRatioNumerator	Numerator of the pixel aspect ratio.
inPixelAspectRatioDenominator	Denominator of the pixel aspect ratio.
inRenderQuality	Use one of the PrRenderQuality enumerated values.
inFieldType	Use one of the prFieldType constants.
inDeinterlace	Set to non-zero, to force an explicit deinterlace. Otherwise, the renderer will use the output field setting to determine whether to automatically deinterlace any interlaced sources.
inDeinterlaceQuality	Use one of the PrRenderQuality enumerated values.
inCompositeOnBlack	Set to non-zero, to composite the render on black.

struct SequenceRender_ParamsRecExt

Fill this structure in before calling RenderVideoFrame(), QueueAsyncVideoFrameRender(), or PrefetchMediaWithRenderParameters().

Note

If the frame aspect ratio of the request does not match that of the sequence, the frame will be letterboxed or pillarboxed, rather than stretched to fit the frame.

typedef struct {
  const PrPixelFormat*  inRequestedPixelFormatArray;
  csSDK_int32           inRequestedPixelFormatArrayCount;
  csSDK_int32           inWidth;
  csSDK_int32           inHeight;
  csSDK_int32           inPixelAspectRatioNumerator;
  csSDK_int32           inPixelAspectRatioDenominator;
  PrRenderQuality       inRenderQuality;
  prFieldType           inFieldType;
  csSDK_int32           inDeinterlace;
  PrRenderQuality       inDeinterlaceQuality;
  csSDK_int32           inCompositeOnBlack;
  PrSDKColorSpaceID       inPrSDKColorSpaceID;
} SequenceRender_ParamsRecExt;

Member	Description
inRequestedPixelFormatArray	An array of PrPixelFormats that list your format preferences in order.
inRequestedPixelFormatArrayCount	Size of the pixel format array.
inWidth	Width to render at.
inHeight	Height to render at.
inPixelAspectRatioNumerator	Numerator of the pixel aspect ratio.
inPixelAspectRatioDenominator	Denominator of the pixel aspect ratio.
inRenderQuality	Use one of the PrRenderQuality enumerated values.
inFieldType	Use one of the prFieldType constants.
inDeinterlace	Set to non-zero, to force an explicit deinterlace. Otherwise, the renderer will use the output field setting to determine whether to automatically deinterlace any interlaced sources.
inDeinterlaceQuality	Use one of the PrRenderQuality enumerated values.
inCompositeOnBlack	Set to non-zero, to composite the render on black.
inPrSDKColorSpaceID	Identifies the color space being used.

struct SequenceRender_ParamsRecExt2

Fill this structure in before calling RenderVideoFrame(), QueueAsyncVideoFrameRender(), or PrefetchMediaWithRenderParameters().

Note

If the frame aspect ratio of the request does not match that of the sequence, the frame will be letterboxed or pillarboxed, rather than stretched to fit the frame.

typedef struct {
  const PrPixelFormat*  inRequestedPixelFormatArray;
  csSDK_int32           inRequestedPixelFormatArrayCount;
  csSDK_int32           inWidth;
  csSDK_int32           inHeight;
  csSDK_int32           inPixelAspectRatioNumerator;
  csSDK_int32           inPixelAspectRatioDenominator;
  PrRenderQuality       inRenderQuality;
  prFieldType           inFieldType;
  csSDK_int32           inDeinterlace;
  PrRenderQuality       inDeinterlaceQuality;
  csSDK_int32           inCompositeOnBlack;
  PrSDKColorSpaceID       inPrSDKColorSpaceID;
      PrSDKLUTID                      inPrSDKLUTID;                   // Added to support export LUT
} SequenceRender_ParamsRecExt2;

Member	Description
inRequestedPixelFormatArray	An array of PrPixelFormats that list your format preferences in order.
inRequestedPixelFormatArrayCount	Size of the pixel format array.
inWidth	Width to render at.
inHeight	Height to render at.
inPixelAspectRatioNumerator	Numerator of the pixel aspect ratio.
inPixelAspectRatioDenominator	Denominator of the pixel aspect ratio.
inRenderQuality	Use one of the PrRenderQuality enumerated values.
inFieldType	Use one of the prFieldType constants.
inDeinterlace	Set to non-zero, to force an explicit deinterlace. Otherwise, the renderer will use the output field setting to determine whether to automatically deinterlace any interlaced sources.
inDeinterlaceQuality	Use one of the PrRenderQuality enumerated values.
inCompositeOnBlack	Set to non-zero, to composite the render on black.
inPrSDKColorSpaceID	New in 13.0. Identifies the color space being used.
inPrSDKLUTID	New in 14.4. Identifies the color space being used.

struct SequenceRender_GetFrameReturnRec

Returned from RenderVideoFrame() and passed by PrSDKSequenceAsyncRenderCompletionProc().

typedef struct {
  void*        asyncCompletionData;
  csSDK_int32  returnVal;
  csSDK_int32  repeatCount;
  csSDK_int32  onMarker;
  PPixHand     outFrame;
} SequenceRender_GetFrameReturnRec;

Member	Description
asyncCompletionData	Passed to PrSDKSequenceAsyncRenderCompletionProc() from QueueAsyncVideoFrameRender().
	Not used by RenderVideoFrame().
returnVal	ErrNone, Abort, Done, or an error code.
repeatCount	The number of repeated frames from this frame forward.
	In the output file, this could be writing NULL frames, changing the current frame’s duration, or whatever is appropriate according to the codec.
onMarker	If non-zero, there is a marker on this frame.
outFrame	Returned from RenderVideoFrame(). Not returned from PrSDKSequenceAsyncRenderCompletionProc()

RenderVideoFrame()

The basic, synchronous call to get a rendered frame from the host.

Returns:

• suiteError_NoError if you can continue exporting,
• exportReturn_Abort if the user aborted the export,
• exportReturn_Done if the export has finished, or
• an error code.

prSuiteError (*RenderVideoFrame)(
  csSDK_uint32                       inVideoRenderID,
  PrTime                             inTime,
  SequenceRender_ParamsRec*          inRenderParams,
  PrRenderCacheType                  inCacheFlags,
  SequenceRender_GetFrameReturnRec*  getFrameReturn);

Member	Description
inVideoRenderID	Pass in the outVideoRenderID returned from MakeVideoRenderer().
	This gives the host the context of the video render.
inTime	The frame time requested.
inRenderParams	The details of the render.
inCacheFlags	One or more cache flags.
getFrameReturn	Passes back a structure that contains info about the frame returned, and the rendered frame itself.

GetFrameInfo()

Gets information about a given frame.

Currently, SequenceRender_FrameInfoRec only contains repeatCount, which is the number of repeated frames from this frame forward.

prSuiteError (*GetFrameInfo)(
  csSDK_uint32                 inVideoRenderID,
  PrTime                       inTime,
  SequenceRender_FrameInfoRec*  outFrameInfo);

SetAsyncRenderCompletionProc()

Register a notification callback for getting asynchronously rendered frames when the render completes.

asyncGetFrameCallback should have the signature described in PrSDKSequenceAsyncRenderCompletionProc below.

prSuiteError (*SetAsyncRenderCompletionProc)(
  csSDK_uint32                            inVideoRenderID,
  PrSDKSequenceAsyncRenderCompletionProc  asyncGetFrameCallback,
  long                                    callbackRef);

Member	Description
inVideoRenderID	Pass in the outVideoRenderID returned from MakeVideoRenderer().
	This will be passed to PrSDKSequenceAsyncRenderCompletionProc.
asyncGetFrameCallback	The notification callback.
inCallbackRef	A pointer holding data private to the exporter.
	This could be, for example, a pointer to an exporter instance. This will also be passed to PrSDKSequenceAsyncRenderCompletionProc.

PrSDKSequenceAsyncRenderCompletionProc()

Use this function signature for your callback used for async frame notification, passed to SetAsyncRenderCompletionProc.

Error status (error or abort) is returned in inGetFrameReturn.

void (*PrSDKSequenceAsyncRenderCompletionProc)(
  csSDK_uint32                      inVideoRenderID,
  void*                              inCallbackRef,
  PrTime                            inTime,
  PPixHand                          inRenderedFrame,
  SequenceRender_GetFrameReturnRec  *inGetFrameReturn);

Member	Description
inVideoRenderID	The outVideoRenderID that the exporter passed to SetAsyncRenderCompletionProc earlier.
inCallbackRef	A pointer that the exporter sets using SetAsyncRenderCompletionProc().
	This could be, for example, a pointer to an exporter instance.
inTime	The frame time requested.
inRenderedFrame	The rendered frame. The exporter is reponsible for disposing of this PPixHand using the Dispose() call in the PPix Suite.
inGetFrameReturn	A structure that contains info about the frame returned, and it includes the inAsyncCompletionData originally passed to QueueAsyncVideoFrameRender().

QueueAsyncVideoFrameRender()

Use this call rather than RenderVideoFrame() to queue up a request to render a specific frame asynchronously.

The rendering can happen on a separate thread or processor.

When the render is completed, the PrSDKSequenceAsyncRenderCompletionProc that was set using SetAsyncRenderCompletionProc will be called.

prSuiteError (*QueueAsyncVideoFrameRender)(
  csSDK_uint32               inVideoRenderID,
  PrTime                     inTime,
  csSDK_uint32*              outRequestID,
  SequenceRender_ParamsRec*  inRenderParams,
  PrRenderCacheType          inCacheFlags,
  void*                      inAsyncCompletionData);

Member	Description
inVideoRenderID	Pass in the outVideoRenderID returned from MakeVideoRenderer().
	This gives the host the context of the video render.
inTime	The frame time requested.
outRequestID	Passes back a request ID, which… doesn’t seem to have any use.
inRenderParams	The details of the render.
inCacheFlags	One or more cache flags.
inAsyncCompletionData	This data will be passed to the PrSDKSequenceAsyncRenderCompletionProc in inGetFrameReturn.asyncCompletionData.

PrefetchMedia()

Prefetch the media needed to render this frame. This is a hint to the importers to begin reading media needed to render this video frame.

prSuiteError (*PrefetchMedia)(
  csSDK_uint32  inVideoRenderID,
  PrTime        inFrame);

PrefetchMediaWithRenderParameters()

Prefetch the media needed to render this frame, using all of the parameters used to render the frame.

This is a hint to the importers to begin reading media needed to render this video frame.

prSuiteError (*PrefetchMediaWithRenderParameters)(
  csSDK_uint32               inVideoRenderID,
  PrTime                     inTime,
  SequenceRender_ParamsRec*  inRenderParams);

CancelAllOutstandingMediaPrefetches()

Cancel all media prefetches that are still outstanding.

prSuiteError (*PrefetchMedia)(
  csSDK_uint32  inVideoRenderID);

IsPrefetchedMediaReady()

Check on the status of a prefetch request.

prSuiteError (*IsPrefetchedMediaReady)(
  csSDK_uint32  inVideoRenderID,
  PrTime        inTime,
  prBool*       outMediaReady);

MakeVideoRendererForTimeline()

Similar to MakeVideoRenderer, but for use by renderer plugins.

Creates a video renderer, in preparation to get rendered video from the host.

The TimelineID in question must refer to a top-level sequence.

prSuiteError (*MakeVideoRendererForTimeline)(
  PrTimelineID   inTimeline,
  csSDK_uint32*  outVideoRendererID);

MakeVideoRendererForTimelineWithFrameRate()

Similar to MakeVideoRendererForTimeline, with an additional frame rate parameter.

This is useful for the case of a nested multicam sequence.

prSuiteError (*MakeVideoRendererForTimelineWithFrameRate)(
  PrTimelineID   inTimeline,
  PrTime         inFrameRate,
  csSDK_uint32*  outVideoRendererID);

ReleaseVideoRendererForTimeline()

Similar to ReleaseVideoRenderer, but for use by renderer plugins. Release the video renderer when the renderer plugin is done requesting video.

prSuiteError (*ReleaseVideoRendererForTimeline)(
  csSDK_uint32  inVideoRendererID);

RenderVideoFrameAndConformToPixelFormat()

New in CS5.5. Similar to RenderVideoFrame., but conforms the resulting frame to a specific pixel format.

Allows an exporter to request a frame in a specific pixel format.

prSuiteError (*RenderVideoFrameAndConformToPixelFormat)(
  csSDK_uint32                       inVideoRenderID,
  PrTime                             inTime,
  SequenceRender_ParamsRec*          inRenderParams,
  PrRenderCacheType                  inCacheFlags,
  PrPixelFormat                      inConformToFormat,
  SequenceRender_GetFrameReturnRec*  getFrameReturn);

MakeVideoRendererForTimelineWithStreamLabel()

New in CS6. Similar to MakeVideoRenderer, but is stream label-aware.

Allows an exporter to request rendered frames from multiple video streams.

prSuiteError (*MakeVideoRendererForTimelineWithStreamLabel)(
  PrTimelineID      inTimeline,
  PrSDKStreamLabel  inStreamLabel,
  csSDK_uint32*     outVideoRendererID);

RenderColorManagedVideoFrame()

Renders a frame of video, using the specified color management.

prSuiteError (*RenderColorManagedVideoFrame)(
        csSDK_uint32                                    inVideoRenderID,
        PrTime                                                  inTime,
        SequenceRender_ParamsRecExt*    inRenderParamsExt,
        PrRenderCacheType                               inCacheFlags,
        SequenceRender_GetFrameReturnRec*       getFrameReturn);

QueueAsyncColorManagedVideoFrameRender()

Queues a render for a frame of video, using the specified color management.

prSuiteError (*QueueAsyncColorManagedVideoFrameRender)(
        csSDK_uint32                                    inVideoRenderID,
        PrTime                                                  inTime,
        csSDK_uint32*                                   outRequestID,
        SequenceRender_ParamsRecExt*    inRenderParamsExt,
        PrRenderCacheType                               inCacheFlags,
        void*                                                   inAsyncCompletionData);

PrefetchColorManagedMedia()

Pre-fetches a frame of color-managed media.

prSuiteError (*PrefetchColorManagedMedia)(
        csSDK_uint32            inVideoRenderID,
        PrTime                          inFrame,
        PrSDKColorSpaceID inPrSDKColorSpaceID);

PrefetchColorManagedMediaWithRenderParameters()

Pre-fetches a frame of color-managed media, using the specified render parameters.

prSuiteError (*PrefetchColorManagedMediaWithRenderParameters)(
        csSDK_uint32                                    inVideoRenderID,
        PrTime                                                  inTime,
        SequenceRender_ParamsRecExt*    inRenderParamsExt);

RenderColorManagedVideoFrameAndConformToPixelFormat()

Renders a frame of color-managed media, to the specified pixel format.

prSuiteError (*RenderColorManagedVideoFrameAndConformToPixelFormat)(
        csSDK_uint32                                    inVideoRenderID,
        PrTime                                                  inTime,
        SequenceRender_ParamsRecExt*    inRenderParamsExt,
        PrRenderCacheType                               inCacheFlags,
        PrPixelFormat                                   inConformToFormat,
        SequenceRender_GetFrameReturnRec*       getFrameReturn);

RenderColorManagedVideoFrame2()

Renders a frame of color-managed media, to the specified pixel format, using settings specified in SequenceRender_ParamsRecExt2.

prSuiteError (*RenderColorManagedVideoFrame2)(
        csSDK_uint32                    inVideoRenderID,
        PrTime                          inTime,
        SequenceRender_ParamsRecExt2*   inRenderParamsExt2,
        PrRenderCacheType               inCacheFlags,
        SequenceRender_GetFrameReturnRec*   outGetFrameReturn);

QueueAsyncColorManagedVideoFrameRender2()

Queues a request for a frame of color-managed media, to the specified pixel format, using settings specified in SequenceRender_ParamsRecExt2.

prSuiteError (*QueueAsyncColorManagedVideoFrameRender2)(
        csSDK_uint32                    inVideoRenderID,
        PrTime                          inTime,
        csSDK_uint32*                   outRequestID,
        SequenceRender_ParamsRecExt2*   inRenderParamsExt2,
        PrRenderCacheType               inCacheFlags,
        void*                           inAsyncCompletionData);

PrefetchColorManagedMediaWithRenderParameters2()

Pre-fetches a request for a frame of color-managed media, to the specified pixel format, using settings specified in SequenceRender_ParamsRecExt2.

prSuiteError(*PrefetchColorManagedMediaWithRenderParameters2)(
        csSDK_uint32                    inVideoRenderID,
        PrTime                          inTime,
        SequenceRender_ParamsRecExt2*   inRenderParamsExt2);

RenderColorManagedVideoFrameAndConformToPixelFormat2()

Renders a frame of color-managed media, to the specified pixel format, using settings specified in SequenceRender_ParamsRecExt2.

prSuiteError (*RenderColorManagedVideoFrameAndConformToPixelFormat2)(
        csSDK_uint32                    inVideoRenderID,
        PrTime                          inTime,
        SequenceRender_ParamsRecExt2*   inRenderParamsExt2,
        PrRenderCacheType               inCacheFlags,
        PrPixelFormat                   inConformToFormat,
        SequenceRender_GetFrameReturnRec*   outGetFrameReturn);

---

PF Utility Suite

Utility functions for use by AE style effect plugins, running in Premiere Pro.

Version 11, new in 15.0, adds GetVideoResolutionString.

GetFilterInstanceID()

Gets the filter ID for the current effect reference.

prSuiteError(*GetFilterInstanceID)(
  PF_ProgPtr    effect_ref,
  A_long*       outFilterInstanceID);

GetMediaTimecode()

Retrieves formatted timecode, as well as the currently active video frame.

prSuiteError(*GetMediaTimecode)(
  PF_ProgPtr      effect_ref,
  A_long*         outCurrentFrame,
  PF_TimeDisplay* outTimeDisplay);

GetClipSpeed()

Retrieves the speed multiplier of the clip.

prSuiteError(*GetClipSpeed)(
              PF_ProgPtr effect_ref,
              double* speed);

GetClipDuration()

Retrieves the duration of the clip.

prSuiteError(*GetClipDuration)(
              PF_ProgPtr effect_ref,
              A_long* frameDuration);

GetClipStart()

Retrieves the start time of the clip.

prSuiteError(*GetClipStart)(
        PF_ProgPtr effect_ref,
        A_long* frameDuration);

GetUnscaledClipDuration()

Retrieves the duration of the clip, unaffected by any speed or retiming changes.

prSuiteError(*GetUnscaledClipDuration)(
              PF_ProgPtr effect_ref,
              A_long* frameDuration);

GetUnscaledClipStart()

Retrives the start time of the clip, unaffected by any speed or retiming changes.

prSuiteError(*GetUnscaledClipStart)(
              PF_ProgPtr effect_ref,
              A_long* frameDuration);

GetTrackItemStart()

Gets the start time of the track item.

prSuiteError(*GetTrackItemStart)(
              PF_ProgPtr    effect_ref,
              A_long*       frameDuration);

GetMediaFieldType()

Retrieves the filed type in use with the media.

prSuiteError(*GetMediaFieldType)(
              PF_ProgPtr    effect_ref,
              prFieldType*  outFieldType); // prFieldsNone, prFieldsUpperFirst, prFieldsLowerFirst, prFieldsUnknown

GetMediaFrameRate()

Gets the number of ticks per frame, for the media.

prSuiteError(*GetMediaFrameRate)(
  PF_ProgPtr  effect_ref,
  PrTime*     outTicksPerFrame);

GetContainingTimelineID()

Gets the ID of the timeline containing the clip to which the effect is applied.

prSuiteError(*GetContainingTimelineID)(
              PF_ProgPtr    effect_ref,
              PrTimelineID* outTimelineID);

GetClipName()

Gets the name of the clip to which the effect is applied (or the master clip).

prSuiteError(*GetClipName)(
              PF_ProgPtr    effect_ref,
              A_Boolean     inGetMasterClipName,
              PrSDKString*  outSDKString);

EffectWantsCheckedOutFramesToMatchRenderPixelFormat()

Indicates that the effect wants to received checked out frames, in the same format used for destination rendering.

prSuiteError(*EffectWantsCheckedOutFramesToMatchRenderPixelFormat)(
        PF_ProgPtr  effect_ref);

EffectDependsOnClipName()

Indicates (based on second parameter) whether the effect depends on the name of the clip to which it is applied.

prSuiteError(*EffectDependsOnClipName)(
              PF_ProgPtr    effect_ref,
              A_Boolean     inDependsOnClipName);

SetEffectInstanceName()

prSuiteError(*SetEffectInstanceName)(
              PF_ProgPtr effect_ref,
              const PrSDKString* inSDKString);

GetFileName()

Retrieves the name of the media file to which the effect instance is applied.

prSuiteError(*GetFileName)(
              PF_ProgPtr      effect_ref,
              PrSDKString*    outSDKString);

GetOriginalClipFrameRate()

Retrieves the original (non-interpreted, un-re-timed) frame rate, of the media to which the effect instance is applied.

prSuiteError(*GetOriginalClipFrameRate)(
              PF_ProgPtr    effect_ref,
              PrTime*       outTicksPerFrame);

GetSourceTrackMediaTimecode()

Retrieves the source media timecode for the specified frame within the specified layer, with or without transforms and start time offsets applied.

prSuiteError(*GetSourceTrackMediaTimecode)(
              PF_ProgPtr      effect_ref,
              csSDK_uint32    inLayerParamIndex,
              bool            inApplyTransform,
              bool            inAddStartTimeOffset,
              A_long*         outCurrentFrame);

GetSourceTrackClipName()

Retrieves the name of the layer in use by the effect instance.

prSuiteError(*GetSourceTrackClipName)(
              PF_ProgPtr      effect_ref,
              csSDK_uint32    inLayerParamIndex,
              A_Boolean       inGetMasterClipName,
              PrSDKString*    outSDKString);

GetSourceTrackFileName()

Retrieves the file name of the source track item for the specified layer parameter.

prSuiteError(*GetSourceTrackFileName)(
              PF_ProgPtr      effect_ref,
              csSDK_uint32    inLayerParamIndex,
              PrSDKString*    outSDKString);

EffectDependsOnClipName2()

Specifies whether the effect instance depends on the specified layer parameter.

prSuiteError(*EffectDependsOnClipName2)(
              PF_ProgPtr    effect_ref,
              A_Boolean     inDependsOnClipName,
              csSDK_uint32  inLayerParamIndex);

GetMediaTimecode2()

Retrieves formatted timecode and current frame number, with or without trims applied.

prSuiteError(*GetMediaTimecode2)(
              PF_ProgPtr      effect_ref,
              bool            inApplyTrim,
              A_long*         outCurrentFrame,
              PF_TimeDisplay* outTimeDisplay);

GetSourceTrackMediaTimecode2()

Given a specific sequence time, retrieves the source track media timecode for the specified layer parameter.

prSuiteError(*GetSourceTrackMediaTimecode2)(
              PF_ProgPtr      effect_ref,
              csSDK_uint32    inLayerParamIndex,
              bool            inApplyTransform,
              bool            inAddStartTimeOffset,
              PrTime          inSequenceTime,
              A_long*         outCurrentFrame);

GetSourceTrackClipName2()

Retrieves the clip name used by the specific layer parameter.

prSuiteError(*GetSourceTrackClipName2)(
              PF_ProgPtr      effect_ref,
              csSDK_uint32    inLayerParamIndex,
              A_Boolean       inGetMasterClipName,
              PrSDKString*    outSDKString,
              PrTime          inSequenceTime);

GetSourceTrackFileName2()

Retreives the clip name in use by the specified layer parameter.

prSuiteError(*GetSourceTrackFileName2)(
              PF_ProgPtr    effect_ref,
              csSDK_uint32  inLayerParamIndex,
              PrSDKString*  outSDKString,
              PrTime        inSequenceTime);

GetCommentString()

Retrieves the comment string associated with the specified source track item, at the specified time.

prSuiteError(*GetCommentString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetLogNoteString()

Retrieves the log note associated with the source track, at the specified time.

prSuiteError(*GetLogNoteString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetCameraRollString()

Retrieves the log note associated with the source track, at the specified time.

prSuiteError(*GetCameraRollString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetClientMetadataString()

Retrieves the metadata string associated with the source track, at the specified time.

prSuiteError(*GetClientMetadataString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetDailyRollString()

Retrieves the daily roll string associated with the source track, at the specified time.

prSuiteError(*GetDailyRollString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetDescriptionString()

Retrieves the daily roll string associated with the source track, at the specified time.

prSuiteError(*GetDescriptionString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetLabRollString()

Retrieves the lab roll string associated with the source track, at the specified time.

prSuiteError(*GetLabRollString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetSceneString()

Retrieves the scene string associated with the source track, at the specified time.

prSuiteError(*GetSceneString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetShotString()

Retrieves the shot string associated with the source track item, at the specified time.

prSuiteError(*GetShotString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetTapeNameString()

Retrieves the tape name string associated with the source track item, at the specified time.

prSuiteError(*GetTapeNameString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetVideoCodecString()

Retrieves a string representing the video codec associated with the source track item, at the specified time.

prSuiteError(*GetVideoCodecString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetGoodMetadataString()

Retrieves a string representing the “good” state of the source track item, at the specified time.

prSuiteError(*GetGoodMetadataString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetSoundRollString()

Retrieves a string representing the “sound roll” state of the source track item, at the specified time.

prSuiteError(*GetSoundRollString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);

GetSequenceTime()

Retrieves the timebase of the sequence in which the effect is applied.

prSuiteError(*GetSequenceTime)(
              PF_ProgPtr  inEffectRef,
              PrTime*     outSequenceTime);

GetSoundTimecode()

Retrieves the frame of the specified source time.

prSuiteError(*GetSoundTimecode)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              A_long*       outCurrentFrame);

GetOriginalClipFrameRateForSourceTrack()

Retrieves the original “ticks per frame” for the specified source track.

prSuiteError(*GetOriginalClipFrameRateForSourceTrack)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime*       outTicksPerFrame);

GetMediaFrameRateForSourceTrack()

Retrieves the media frame rate for the specified source track.

prSuiteError(*GetMediaFrameRateForSourceTrack)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrTime*       outTicksPerFrame);

GetSourceTrackMediaActualStartTime()

Retrieves the start time of the specified layer parameter.

prSuiteError(*GetSourceTrackMediaActualStartTime)(
              PF_ProgPtr      inEffectRef,
              csSDK_uint32    inLayerParamIndex,
              PrTime          inSequenceTime,
              PrTime*         outClipActualStartTime);

IsSourceTrackMediaTrimmed()

Retrieves whether the source track item has been trimmed.

prSuiteError(*IsSourceTrackMediaTrimmed)(
              PF_ProgPtr      inEffectRef,
              csSDK_uint32    inLayerParamIndex,
              PrTime          inSequenceTime,
              bool*           outTrimApplied);

IsMediaTrimmed()

Retrieves whether the track item has been trimmed.

prSuiteError(*IsMediaTrimmed)(
              PF_ProgPtr    inEffectRef,
              PrTime        inSequenceTime,
              bool*         outTrimApplied);

IsTrackEmpty()

Retrieves whether, for the specified layer parameter, the track is empty.

prSuiteError(*IsTrackEmpty)(
              PF_ProgPtr      inEffectRef,
              csSDK_uint32    inLayerParamIndex,
              PrTime          inSequenceTime,
              bool*           outIsTrackEmpty);

IsTrackItemEffectAppliedToSynthetic()

Retrieves whether the effect is applied to a track item backed by a synthetic importer.

prSuiteError(*IsTrackItemEffectAppliedToSynthetic)(
              PF_ProgPtr    inEffectRef,
              bool*         outIsTrackItemEffectAppliedToSynthetic);

GetSourceTrackCurrentMediaTimeInfo()

Retrieves the current media time, including ticks per frame and a formatted string representing that time.

prSuiteError(*GetSourceTrackCurrentMediaTimeInfo)(
              PF_ProgPtr      effect_ref,
              csSDK_uint32    inLayerParamIndex,
              bool            inUseSoundTimecodeAsStartTime,
              PrTime          inSequenceTime,
              PrTime*         outCurrentMediaTime,
              PrTime*         outMediaTicksPerFrame,
              PF_TimeDisplay* outMediaTimeDisplay);

GetSequenceZeroPoint()

Retrieves the zero point (start time) of the sequence in which the effect is applied.

prSuiteError(*GetSequenceZeroPoint)(
              PF_ProgPtr    inEffectRef,
              PrTime*       outZeroPointTime);

GetSourceTrackCurrentClipDuration()

Retrieves the duration of the clip, at the specified layer index, at inSequenceTime.

prSuiteError(*GetSourceTrackCurrentClipDuration)(
              PF_ProgPtr        inEffectRef,
              csSDK_uint32      inLayerParamIndex,
              PrTime            inSequenceTime,
              PrTime*           outClipDuration);

GetSequenceDuration()

Retrieves the duration of the sequence in which the effect is applied.

prSuiteError(*GetSequenceDuration)(
              PF_ProgPtr    inEffectRef,
              PrTime*       outSequenceDuration);

      /*
      ** Get the video resolution string, formatted as a 'width x height',
      ** of the clip (ie, track item) at inSequenceTime on inSourceTrack.
      ** Set inSourceTrack to -1 to query the top-most clip at inSequenceTime
      ** (only if effect is on an adjustment layer)
      */

GetVideoResolutionString()

Retrieve a string representing the dimensions of the track item to which the effect is applied.

prSuiteError(*GetVideoResolutionString)(
              PF_ProgPtr    inEffectRef,
              int32_t       inSourceTrack,
              PrTime        inSequenceTime,
              PrSDKString*  outSDKString);