DeviceRec¶

A device controller is passed a handle to a DeviceRec with every selector. Yes, we know, it’s a monster.

typedef struct {
  PrMemoryHandle        deviceData;
  short                 command;
  short                 mode;
  csSDK_int32           timecode;
  short                 timeformat;
  short                 timerate;
  csSDK_int32           features;
  short                 error;
  short                 preroll;
  CallBackPtr           callback;
  PauseProcPtr          PauseProc;
  ResumeProcPtr         ResumeProc
  long                  xtimecode;
  long                  keycode;
  short                 editmode;
  short                 exteditmode;
  Print2TapeProcPtr     PrintProc;
  HWND                  parentWindow;
  piSuitesPtr           piSuites;
  char*                 displayName;
  TimecodeUpdatePtr     TimecodeUpdateProc;
  void*                 classID;
  long                  version;
  short                 videoStreamIsDrop;
  short                 autoDetectDropness;
  char*                 currentDeviceIDStr;
  long                  preferredScale;
  unsigned long         preferredSampleSize;
  DroppedFrameCountPtr  DroppedFrameProc;
  csSDK_uint32          exportAudioChannels;
  csSDK_uint16          exportFlags;
  csSDK_int32           delayFrames;
} DeviceRec, *DevicePtr, \*\*DeviceHand;

`deviceData`	Handle to private data allocated during dsInit or dsRestart. Saved in the application preferences, and restored when the app is restarted.
`command`	The command to be performed when you receive `dsExecute`.
`mode`	Used in three ways. For dsExecute/cmdNewMode, mode contains your device’s new mode. For dsExecute/cmdStatus, mode is where you indicate the device’s current mode (the last mode reported will still be there). For dsExecute/cmdShuttle, mode contains the shuttle rate (-100 to 100).
`timecode`	Used three ways. For dsExecute/cmdGoto and dsExecute/cmdLocate, the timecode field indicates the timecode to which your should move. For dsExecute/cmdStatus, return the deck’s current timecode position via the timecode field, where: `kInvalidTimecode` will display “N/A” (not available), `-2` will blank the timecode display, and `-3` will display “Searching…”. For dsExecute/cmdJogTo, timecode specifies the location to which you should jog.
`timeformat`	Reports the format of timecode for a dsExecute/cmdStatus; 0 for non-drop frame, 1 for drop-frame.
`timerate`	Reports the frame rate of timecode for a dsExecute/cmdStatus call. Set to 24, 25, 30, or 60. Note, for 23.976 fps footage, set timerate to 24, and timeformat to 1. 24 fps timecode will be used, as expected. Of course, there is no such thing as 24 fps drop-frame timecode, but this was the way 23.976 fps support was added within the constraints of the existing API.
`features`	Reports the device’s features in response to a dsExecute/cmdGetFeatures call.
`error`	Set this field to an appropriate error code and return a non-zero value from your device controller.
`preroll`	Used by dsExecute/cmdLocate. Preroll is how far before (smaller timecode) the seek time specified in timecode you should seek. The preroll value is the product of a calibration sequence the user performs.
`callback`	Pointer to a callback to use during dsExecute/cmdLocate to determine if the user is attempting to abort. typedef csSDK_int32 (*CallBackPtr) (void); If the return value is non-zero, the user has attempted to abort.
`PauseProc`	Pointer to a callback that you can use to temporarily pause any sequence grabber operations in a device-controlled window. It is defined as follows: typedef void (*PauseProcPtr) (void);
`ResumeProc`	A pointer to a routine to call to resume sequence capture after calling PauseProc. Every call to `PauseProc` must be matched by a call to `ResumeProc`. typedef void (ResumeProcPtr) (void); Call these routines before putting up an error alert, for instance: ((theData)->PauseProc)(); // your error handler here ((*theData)->ResumeProc)(); If PauseProc isn’t called before putting up an alert (or any other dialog), video will be played over it
`xtimecode`	Duration of the movie being exported (used for the Export to Tape).
`keycode`	Unused.
`editmode`	Can be any combination of the following flags to enable user actions: `insertVideo`, `insertAudio1`, `insertAudio2`, `insertTimeCode`, `insertAssemble`, `insertPreview`
`exteditmode`	Unused.
`PrintProc`	New in 7.0, this callback is no longer needed as the host drives the Edit to Tape rather than the device controller. A pointer to a plugin function Premiere calls to print to tape. csSDK_int32 (Print2TapeProcPtr)( PrMemoryHandle deviceHand, long selector); `deviceHand` is passed to the plugin in DeviceRec. selector can be setupWaitProc, idle, or complete. See cmdInsertEdit*.
`piSuites`	Pointer to universal callback suites.
`displayName`	A 255 character string to display the name of the device the plugin is currently controlling.
`TimecodeUpdateProc`	During `cmdLocate`, use this to report timecode. void (TimecodeUpdatePtr)( csSDK_int32 outTimecode, void outClassID);
`classID`	Used for `TimecodeUpdateProc`
`version`	Premiere informs the device controller of the API version, so the plugin can modify it’s behavior to support multiple versions, if desired. Premiere Pro CC, October 2013 update - kDeviceControlAPIVersion14 Premiere Pro CC, July 2013 update - kDeviceControlAPIVersion13 Premiere Pro CC - kDeviceControlAPIVersion12 Premiere Pro CS6.0.1 - kDeviceControlAPIVersion11 Premiere Pro CS5.5 - kDeviceControlAPIVersion105 Premiere Pro CS5 - kDeviceControlAPIVersion10 Premiere Pro CS3 and CS4 - kDeviceControlAPIVersion9
`videoStreamIsDrop`	If `autoDetectDropness` was set earlier, and the recorder called `FormatChangedFunc` to provide the drop-frame attribute of the timecode, 0Premiere will call cmdSetDropness and use this to tell the device controller if the video stream is drop-frame.
`autoDetectDropness`	Set this to true if you want Premiere to notify the device controller whether or not the video stream uses drop-frame timecode. Premiere will get this timecode information from the active recorder. The result will be sent during cmdSetDropness in videoStreamIsDrop.
`currentDeviceIDStr`	For internal use only.
`preferredScale`	The current timebase. Use this rather than calling `piSuites->utilFuncs->getSettings(kSettingsProjectScale)`.
`preferredSampleSize`	New in Premiere Pro CS3. The current timebase. Use this rather than calling `piSuites->utilFuncs->getSettings(kSetting sProjectSampleSize)`.
`DroppedFrameProc`	New in 7.0, if the Edit to Tape panel is supported, this callback is no longer needed as Abort on Dropped Frames is handled transparently to the device controller. In Premiere Pro CS6.0.1, use this callback to query the current number of frames dropped during an insert edit. A device controller can use this to provide the feature to abort an Edit to Tape if frames are dropped. csSDK_int32 (DroppedFrameProc)( void inClassID);
`exportAudioChannels`	New in 7.0. During cmdGetFeatures, the device controller should set the bits corresponding to the audio channels available on the device. Then later during the record commands, if the device supports audio channel selection, the bits will be set by the host corresponding to audio channels to export: A1 == bit 0, A2 == bit 1, etc.
`exportFlags`	New in 7.0. During the record commands, one or more of the following may be set: exportVideo - set if user has checked the Video checkbox in the Edit to Tape panel processCCData - set if user has checked the Insert Closed Caption Data checkbox in the Edit to Tape panel previewEdit - set if user has pressed the Preview button in the Edit to Tape panel
`delayFrames`	New in CC July 2013. If fCanDelayMovieStart was set, during an Edit to Tape, this will be the value as set by the user (in frames) in the Edit to Tape panel, and Premiere Pro will let the device controller handle the Delay Movie Start.