Legacy Callback Suites

piSuites

These callbacks are available to all plug-ins, although many of these callbacks are only appropriate for specific plug-in 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 plug-in). 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 plug-ins 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 plug-ins (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. 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 plug-in. 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 plug-in 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. 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 plug-in 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 plug-in. 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 plug-in 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. Valid modes are cbBlend, cbInterp, and cbMaskHdl For 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) While much slower than cbBlend, cbInterp 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. Pass 0 for no clipping. The prRgn 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);