Legacy Callback Suites

piSuites

These callbacks are available to all plugins, although many of these callbacks are only appropriate for specific plugin types.

typedef struct {
  int                   piInterfaceVer;
  PlugMemoryFuncsPtr    memFuncs;
  PlugWindowFuncsPtr    windFuncs;
  PlugppixFuncsPtr      ppixFuncs;
  PlugUtilFuncsPtr      utilFuncs;
  PlugTimelineFuncsPtr  timelineFuncs;
} piSuites, *piSuitesPtr;

Member	Description
`piInterfaceVer`	API version
	- Premiere Pro CS4 - `PR_PISUITES_VERSION_9`
	- Premiere Pro CS3 - `PR_PISUITES_VERSION_8`
	- Premiere Pro 2.0 - `PR_PISUITES_VERSION_7`
	- Premiere Pro 1.5.1 - `PR_PISUITES_VERSION_6`
	- Premiere Pro 1.5 - `PR_PISUITES_VERSION_5`
	- Premiere Pro 1.0 - `PR_PISUITES_VERSION_4`
	- Premiere 6.x - `PR_PISUITES_VERSION_3`
	- Premiere 5.1 - `PR_PISUITES_VERSION_2`
	- Premiere 5.0 - `PR_PISUITES_VERSION_1`
memfuncs	Pointer to memory functions
windFuncs	Pointer window functions
ppixFuncs	Pointer PPix functions
utilFuncs	Pointer to utility functions.
	In the utilFuncs, the getSPBasicSuite callback provides access to the SweetPea Suites, which are used for most of the newer functions.
timelineFuncs	Pointer to timeline functions

Memory Functions

Memory and handle allocation. Where possible, use the PPix Creator Suite for PPix-specific allocation.

Strings passed to and from Premiere in API structures are always null-terminated C strings.

Function	Description
`newPtr`	Allocates a block of memory, returns a pointer to the new block.
	char* newPtr (csSDK_uint32 size);
`newPtrClear`	Equivalent to newPtr, but initializes the memory to 0.
	char* newPtrClear (csSDK_uint32 size);
`setPtrSize`	Resizes an allocated memory block.
	void setPtrSize ( PrMemoryPtr *ptr, csSDK_uint32 newsize);
`getPtrSize`	Returns size in bytes of an allocated memory block.
	csSDK_int32 getPtrSize (char *ptr);
`disposePtr`	Frees an allocated memory block.
	void disposePtr (char *ptr);
`newHandle`	Allocates a block of memory, returning a handle to it.
	char** newHandle (csSDK_uint32 size);
`newHandleClear`	Equivalent to newHandle, but initializes the memory to 0.
	char** newHandleClear (csSDK_uint32 size);
`setHandleSize`	Resizes an allocated memory handle.
	csSDK_int16 setHandleSize ( char **PrMemoryHandle, csSDK_uint32 newsize);
`getHandleSize`	Returns the size (in bytes) of an allocated block.
	csSDK_int32 getHandleSize ( char **PrMemoryHandle);
`disposeHandle`	Disposes of a previously allocated handle.
	void disposeHandle (char **PrMemoryHandle);
`lockHandle` `unlockHandle`	These legacy functions are deprecated and should no longer be used.

Window Functions

Window management routines. Superceded by the Window Suite.

Function	Description
`updateAllWindows`	Updates all windows. Windows only, doesn’t work on Mac OS.
	void updateAllWindows (void);
`getMainWnd`	Returns the main application HWND.
	void getMainWnd (void);

PPix Functions

Used to manipulate a PPix. Superceded by the PPix Creator Suite for PPix allocation and the PPix Suite for general PPix functions.

Function	Description
`ppixGetPixels`	Returns a pointer to the array of pixels contained in a PPix.
	char* ppixGetPixels (PPixHand pix);
`ppixGetBounds`	Returns the bounds of a PPix.
	void ppixGetBounds ( PPixHand pix; prRect *bounds);
`ppixGetRowbytes`	Returns the rowbytes of a PPix so you can properly parse the pixels returned by ppixGetPixels.
	int ppixGetRowbytes (PPixHand pix);
`ppixNew`	Allocates and returns a handle to a new PPix, with specified bounds.
	Since this is an older call, the pixel format is hardcoded to BGRA_4444_8u.
	PPixHandle ppixNew (prRect *bounds);
`ppixDispose`	Frees a PPixHand.
	void ppixDispose (PPixHand pix);
`ppixLockPixels` `ppixUnlockPixels`	These legacy functions are deprecated and should no longer be used.
`ppixGetPixelAspectRatio`	Passes back the pixel aspect ratio of a PPixHand.
	Premiere populates the longs with the PAR numerator and denominator.
	int ppixGetPixelAspectRatio ( PPixHand pix, csSDK_uint32 num, csSDK_uint32 den)
`ppixGetAlphaBounds`	Passes back the alpha bounds of a PPixHand.
	void ppixGetAlphaBounds ( PPixHand pix, prRect *alphaBounds)

Utility Functions

Function	Description
`getSerialNumber`	Passes back Premiere’s serial number.
	void getSerialNumber (char* buffer);
	- `buffer`: must be at least 40 characters long.
`getFileTimebase`	Passes back a file’s timebase in a `TDB_TimeRecord` (allocated by the plugin).
	If the file is already in the sequence, it is preferable to get a file’s timebase using the Video Segment Suite to get the `kVideoSegmentProperty_Media_StreamFrameRate`.
	Note: Know your formats. Don’t ask an audio only format for video, you may get unexpected results.
	csSDK_int32 getFileTimebase ( prFileSpec filespec, csSDK_int32 audioOnly, TDB_TimeRecord result);
	- `filespec`: description of the file, use before getFileVideo
	- `audioOnly`: if non-zero, return the audio timebase. If zero, return the video timebase.
	- `result`: the returned timebase
`getFileVideo`	Gets a frame of video (at a specified time) from a file.
	If the file is already in the sequence, it is preferable to get a file’s video using the Clip Render Suite.
	csSDK_int32 getFileVideo ( prFileSpec filespec, csSDK_int32 frame, PPixHand thePort, prRect bounds, csSDK_int32 flags);
	- `filespec`: the description of the file
	- `frame`: the frame to retrieve
	- `thePort`: where the frame will be delivered, allocate prior to calling
	- `bounds`: the boundary of the port
	- `flags`: unused
`getFileVideoBounds`	Passes back the bounds of a file.
	If the file is already in the sequence, it is preferable to get a file’s video bounds using the Clip Render Suite.
	csSDK_int32 getFileVideoBounds ( prFileSpec filespec, prRect bounds);
`getSPBasicSuite`	This very important call returns the SweetPea suite that allows plugins to acquire and release all other SweetPea Suites.
	SPBasicSuite* getSPBasicSuite();
`getFileExtString`	Passes back the list of valid entensions/filter strings given a class of media (see file types constants below).
	csSDK_int32 (plugGetFileExtStringFunc)( csSDK_uint32 fileTypes, char inBuffer, csSDK_uint32 inBufferSize);
	- `kFileTypes_Still`: still media
	- `kFileTypes_AudioOnly`: audio-only media
	- `kFileTypes_AudioVideo`: audio and video media
	- `kFileTypes_AllNoIntrinsics`: all importable media types via importer plugins (no prproj, txt, etc)

Timeline Functions

Function	Description
`getClipVideo`	Superceded by the Clip Render Suite, which provides asynchronous import.
	Retrieves a frame from a clip in a segment tree returned from the Video Segment Suite.
	It can be used by to retrieve and store a still frame, such as a title, for playback.
	!!! warning
	This call is expensive; use it carefully.
	csSDK_int32 getClipVideo ( csSDK_int32 frame, PPixHand thePort, prRect *bounds, csSDK_int32 flags, PrClipID clipData);
	- `frame`: the frame number you’re requesting
	- `thePort`: allocate using the PPix Creator Suite before calling
	- `bounds`: the boundaries of video to return
	- `flags`: either `kGCVFlag_UseFilePixelAspectRatio` or 0. Setting it to `kGCVFlag_UseFilePixelAspectRatio` will return a PPix stamped with the PAR of the file. Setting it to 0 will return a PPix adjusted to the PAR of the project and stamped accordingly. It scales, but does not stretch the PPix to fit the destination PPix that is passed in. So if the destination PPix is larger than the frame asked for, the frame will maintain its frame aspect ratio, letterboxing or pillarboxing the frame with transparent black. To import a frame at its native dimensions, use getClipVideoBounds, allocate the destination PPix using the dimensions returned, and pass the PPixHand and the dimensions into `getClipVideo`. If the frame size is not the same as the sequence size, the frame must be positioned in the composite by the plugin.
	- `clipData`: the clipData handle found in prtFileRec
`getWorkArea`	Passes back two longs with the start and end of the current work area (read-only).
	Set timelineData to the timelineData of the current sequence.
	csSDK_int32 getWorkArea ( PrTimelineID timelineData, csSDK_int32 workAreaStart, csSDK_int32 workAreaEnd);
`getCurrentTimebase`	Passes back the current timebase of the timeline (`scale + sampleSize`).
	void getCurrentTimebase( PrTimelineID timelineData, csSDK_uint32 scale, csSDK_int32 sampleSize);
	- `timelineData`: the timelineData of the current sequence
	- `scale`: the sequence scale
	- `sampleSize`: the sequence sampleSize
`getCurrentPos`	Returns the position of the current time indicator (the position bar set by the user).
	If (-1) is returned, the position bar in the timeline is not present.
	csSDK_int32 getCurrentPos( PrTimelineID timelineData);
	- `timelineData`: the timelineData of the current sequence
`getPreviewFrameEx`	Gets a fully rendered frame from the timeline (all layers).
	Used by video filters and transitions for previews in a modal setup dialog.
	If the return value is -1, an error occurred, but if it is 0, the callback has returned safely.
	Exporters rendering final movies should NOT use this callback.
	csSDK_int32 getPreviewFrameEx( PrTimelineID timelineData, csSDK_int32 inFrame, PPixHand* outRenderedFrame, const prRect* inFrameRect, PrPixelFormat* inRequestedPixelFormatArray, csSDK_int32 inRequestedPixelFormatArrayCount, csSDK_uint32 inPixelAspectRatioNumerator, csSDK_uint32 inPixelAspectRatioDenominator, bool inAlwaysRender);
	- `timelineData`: The timelineData of the current sequence. Pass a timeline handle as provided in EffectRecord, VideoRecord, compDoCompileInfo, or imGetPrefsRec.
	- `inFrame`: The frame to get, specified in the current timebase. If a timelineData handle is specified (first param above), this frame will be relative to the start of the sequence.
	- `outRenderedFrame`: The destination buffer. Allocate prior to this call by the plugin using the PPix Suite. Released by the caller before returning.
`getClipVideoBounds`	Passes back the dimensions of a clip in a sequence. For rolling/ crawling titles, use the Roll/Crawl Suite to get the dimensions instead.
	csSDK_int32 getClipVideoBounds ( PrClipID inClipData, prRect outBounds, csSDK_uint32 outPixelAspectRatioNumerator, csSDK_uint32 *outPixelAspectRatioDenominator);
`getClipVideoEx`	Superceded by the Clip Render Suite, which provides asynchronous import.
	Retrieves a frame from a clip in a segment tree returned from the Video Segment Suite.
	It can be used by to retrieve and store a still frame, such as a title, for playback.
	!!! warning
	This call is expensive; use it carefully.
	csSDK_int32 getClipVideoEx ( csSDK_int32 inFrame, PPixHand outRenderedFrame, const prRect inFrameRect, const PrPixelFormat *inRequestedPixelFormatArray, csSDK_int32 inRequestedPixelFormatArrayCount, csSDK_uint32 inPixelAspectRatioNumerator, csSDK_uint32 inPixelAspectRatioDenominator, PrClipID inClipData);
	- `inFrame`: the frame number you’re requesting, in the timebase of the clip
	- `outRenderedFrame`: Allocated by the host. The plugin should dispose of the PPixHand when done
	- `inFrameRect`: the boundaries of video to return. To import a frame at its native dimensions, use getClipVideoBounds. If the frame size is not the same as the sequence size, the frame must be positioned in the composite by the plugin.
	- `inClipData`: the PrClipID from the video segment

Bottleneck Functions

The pointer to the legacy bottleneck functions is passed only to transitions and video filters.

These functions are not exposed for other plugin types.

These functions are not aware of different pixel formats, and are intended only for 8-bit BGRA processing.

Sample usage:

((*theData)->bottleNecks->StretchBits) (*srcpix,
                                        *dstpix,
                                        &srcbox,
                                        &srcbox,
                                        0,
                                        NULL);

Function	Description
`StretchBits`	Stretches and copies an image, including the alpha channel.
	When the destination is larger than the source, it performs bilinear interpolation for smooth scaling.
	void StretchBits ( PPixHand srcPix, PPixHand dstPix, prRect srcRect, prRect dstRect, int mode, prRgn rgn);
	StretchBits only works on 8-bit PPixs.
	`srcRect` is the area of the source PPix to copy; `dstRect` is used to scale the copy.
	`mode`:
	Valid modes are `cbBlend`, `cbInterp`, and `cbMaskHdl`
	- `cbBlend` - The low byte of the mode defines the amount of blend between the source and destination in a range of 0-255.
	- Example:
	- To blend 30% of the source with the destination, use `cbBlend \^ (30*255/100)`
	- `cbInterp` - While much slower than `cbBlend`, this mode does bilinear interpolation when resizing a source PPix to a larger destination, resulting in a much smoother image.
	- `cbMaskHdl` tells StretchBits that prRgn is a handle to a 1-bit deep buffer the same size as the source and destination PPixs, to be used as a mask.
	`prRgn`: Pass `0` for no clipping. This parameter is only used on Windows.
`DistortPolygon`	Maps the source rectangle to a four-point polygon in the destination.
	void DistortPolygon ( PPixHand src, PPixHand dest, prRect srcbox, prPoint dstpts);
	When scaling up, `DistortPolygon` uses bilinear interpolation; it uses pixel averaging when scaling down.
`MapPolygon`	Maps a four-point src polygon into a four-point polygon (dstpts).
	If the source polygon is a rectangle, it is equivalent to `DistortPolygon`.
	void MapPolygon ( PPixHand src, PPixHand dest, prPoint srcpts, prPoint dstpts );
`DistortFixed`	Equivalent to DistortPolygon, using fixed-point coordinates.
	void DistortFixed ( PPixHand src, PPixHand dest, prRect srcbox, LongPoint dstpts);
`FixedToFixed`	Equivalent to MapPolygon, using fixed-point coordinates.
	void FixedToFixed ( PPixHand src, PPixHand dest, LongPoint srcpts, LongPoint dstpts);
`DoIndexMap`	Image map function.
	void DoIndexMap ( char src, char dst, short row, short, pixwidth, short, height, char lookup1, char lookup2, char *lookup3);
`DoConvolve`	Convolution function.
	void DoConvolve ( unsigned char src, unsigned char dst, short *inmatrix, short, rowBytes, short, width, short, height);