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);