MidiVid Home 
Main Page | Class Hierarchy | Class List | File List | Class Members | File Members | Related Pages

MVPlug Class Reference

Inheritance diagram for MVPlug:

MVBasePlug List of all members.

Detailed Description

When creating an effect or event plugin for MidiVid, you must derive your class object from MVPlug. MVPlug objects are instantiated by MidiVid by calling the MVPlugDesc::CreatePlug() function in the object whose MVPlugDesc::GetID() method returns the same value as this plugin. It is very important that the MVPlugDesc and MVPlug objects return the same values for the GetType() and GetID() functions.

See also:
MVPlugDesc, MVBasePlug, MVSourcePlug


Public Member Functions

 MVPlug ()
 Constructor.
virtual ~MVPlug ()
 Destructor.
virtual long GetNumFiles (void)=0
 Return the number of external files (or sources) that this plug in uses.
virtual const char * GetFileName (long WhichFile)=0
 Return the name of the Nth file in use.
virtual void SetFileName (long WhichFile, char *pNewName)=0
 Change the Nth filename to the new name specified.
virtual bool Startup (void)=0
 Called when a patch change brings the plug-in into scope - Used to initialize before notes are played.
virtual bool Shutdown (void)=0
 Called when a patch change pushes the plug-in out of scope - Used to dump any data loaded by Startup().
virtual bool Assign (HWND hCallWnd)=0
 Assign/Edit a note - Display your config dialog when called.
virtual void NoteOn (void)=0
 Called when your plugin note is pressed.
virtual void NoteOff (void)=0
 Called when your plugin note is released.
virtual void Tick (DWORD dwTimeDelt)=0
 Called every frame while your plugin note is held.
virtual bool Sustain (void)=0
 Return true if you wish to "hold" the note on even after release.
virtual bool Load (TagStream &f)=0
 Called to load your plugin settings while loading a performance.
virtual bool Save (TagStream &f)=0
 Called to save your plugin settings while saving a performance.
virtual int NumParameters (void)=0
 Return the number of modifiable parameters you wish to publish to the knob shelf.
virtual bool ParameterVisible (int Index)=0
 Return true if the given parameter number should be visible based on current settings.
virtual MVParamInfo * GetParamInfo (int Param)=0
 Return a pointer to an MVParamInfo structure providing details about the indicated paramter.
virtual int GetParameter (int Index)=0
 Return the value of the indicated parameter.
virtual void SetParameter (int Index, int Value)=0
 Set a new value for the indicated parameter.

Public Attributes

BYTE Velocity
 The velocity this note was triggered with (1-127).
BYTE Channel
 Which channel this instance of the plugin is running on (0-15).
WORD StartChan
 Which channels this plug-in has been started on (bit mask).

Member Function Documentation

MVPlug::GetNumFiles (  void   )  [pure virtual]
 

This function is used both by the notes window, and by the Bundle Project tool. MidiVid needs to know how many files you have, and needs access to the filenames to display or change them.

Returns:
The number of external files (or sources) that this plug in uses.
See also:
GetFileName, SetFileName

MVPlug::GetFileName (  long  WhichFile  )  [pure virtual]
 

MidiVid calls this function to ask you for the name of one of the files you use.

Parameters:
WhichFile The index of the filename (from 0 to GetNumFiles()-1) that MidiVid is asking about.
Returns:
A pointer to the name of the Nth file in use.
See also:
GetNumFiles, SetFileName

MVPlug::SetFileName (  long  WhichFile,
char *  pNewName
)  [pure virtual]
 

This function is called when the user Bundles a performance. MidiVid requests the names of all files in use by all plugins, copies them into a common folder, and then informs all the plugins of the new paths to the files.

Parameters:
WhichFile The index of the filename to change
pNewName The new name for the file - Copy this string, as it is temporary.
See also:
GetNumFiles, GetFileName

MVPlug::Startup (  void   )  [pure virtual]
 

MidiVid calls the Startup function at a few different times. The most common is when the plugin comes into scope, meaning that the patch the plugin resides in is assigned to a MIDI channel. Startup may also be called when performance options change, modifying the display settings, or after the user has edited settings in the plugin through the Assign function. The Startup function is your chance to perform any startup duties you may need to do in preparation for executing your effect. This can include opening or loading files, pre-fetching data, compiling shaders, querying the system for things like back buffer size, creating geometry, and so on. Any initialization the plugin does that is relatively time consuming should be done here. Startup will be called before NoteOn, Tick, or NoteOff.

Returns:
true if successful, false if you were unable to initialize correctly for any reason.
See also:
Shutdown, NoteOn, NoteOff, Tick

MVPlug::Shutdown (  void   )  [pure virtual]
 

This function is the complement to the Startup function. MidiVid calls Shutdown on your plugin when the plugin goes out of scope, usually when the patch the plugin resides in is unassigned from its channel and replaced with another. Shutdown will also be called before the user edits the plugin, before a display resolution change, and so on.

MVPlug::Assign (  HWND  hCallWnd  )  [pure virtual]
 

This function is called when your plugin is assigned to a note, or when editing a plugin already assigned. Display the dialog box that allows the user to configure your plugin.

Parameters:
hCallWnd The handle of the parent window for your configuration dialog.
Returns:
true if the user accepted their changes and hit OK, false if not.

MVPlug::NoteOn (  void   )  [pure virtual]
 

NoteOn is called for your plugin when the corresponding MIDI note sends a note on event. This function is called to tell your plugin to do any last-moment initialization or setup because its Tick function is about to be called for rendering. Any initialization done here should be relatively fast (IE no more than a millisecond or two) because the note is actually pressed and the user is expecting immediate feedback. The Velocity member is set prior to calling NoteOn. Plugins are advised to postpone rendering until the first Tick() call. This will happen in the same frame as NoteOn, but Tick() calls are sorted by note priority, while NoteOn() calls are processed in the order they are received.

If your plugin allocates temporary display surfaces that must reside in video memory, this is the preferred place to handle the allocation of those surfaces. Since your plugin must share the video memory with up to 128 other plugins loaded in the same patch, if every plugin allocated and held a 640x480 32bit temp buffer, that would be a total of 150Mb of video memory allocated. Use sparingly.

See also:
NoteOff, Tick

MVPlug::NoteOff (  void   )  [pure virtual]
 

NoteOff is called when the corresponding MIDI note sends a note off event, signalling that your plugin should stop rendering. Any temporary space allocated in the NoteOn call should be freed. It is safe to render during the NoteOff call. MidiVid plugins with the "Erase on note off" setting call the IDirect3DDevice9::Clear() function at this time.

See also:
NoteOn, Tick

MVPlug::Tick (  DWORD  dwTimeDelt  )  [pure virtual]
 

Tick is called every frame while the MIDI note your plugin is assigned to is held down. This is the function MidiVid calls to get your plugin to render to the display. You can do pretty much anything you want here, but make sure that you return all D3D renderstate values to their defaults so you don't interfere with the operation of other plugins. This is currently not enforced, due to processing overhead. It is likely that a debug mode will be added later to help track down the offending plugin when problems arise.

Parameters:
dwTimeDelt The number of milliseconds that have passed since the last frame. This value is used to update MVSourcePlug plugins, and is used as a scale for any parameters that change over time, ensuring that your plugin exhibits the same behavior at different frame rates. Do not use any other means of measuring time, as they will not work during non-realtime rendering, such as rendering a performance to a file.
See also:
NoteOn, NoteOff, Startup, Shutdown

MVPlug::Sustain (  void   )  [pure virtual]
 

MidiVid calls the Sustain function to ask your plugin if it should continue to call your Tick function even after the user has released the note. This is useful if the user is triggering notes with a drum machine or other "instant off" device which sends note-off events immediately after a note-on.

Returns:
true if you wish to "hold" the note on even after a note release. Continue to return true until it's time to stop executing this plugin, such as when the video stream is finished, or a specified time has elapsed.

MVPlug::NumParameters (  void   )  [pure virtual]
 

MidiVid calls this function to find out how many "tweakable" parameters this plugin would like exposed on the knob shelf.

Returns:
The number of modifiable parameters you wish to publish to the knob shelf, or zero if you have none.

MVPlug::ParameterVisible (  int  Index  )  [pure virtual]
 

MidiVid calls this function whenever your plugin configuration is changed with the MVPlug::Assign() function. It is used to ask if, given the current plugin settings, the indicated parameter should be visible or not. For example, if the user has disabled "Color key" mode, you no longer need to display the controls for changing the key color or key tolerance.

Parameters:
Index The index of the parameter in question.
Returns:
true if the given parameter number should be visible based on current settings

MVPlug::GetParamInfo (  int  Param  )  [pure virtual]
 

This function is called to request information about a specific plugin parameter value. The MVParamInfo structure contains the range of the parameter, the default value, whether the knob should wrap or not, and the display name and unique identifier of this parameter. Most plugins simply return a pointer to a static instance of this data, like this:

Sample usage: 

static MVParamInfo MyInfo[] = {
    // Min   Max  Def  Wrap    UID    Name
    {    0,  255,   0, false, 'KDST', "Key Dist"},
    { -360,  360,   0, true,  'ROTA', "Rotate"},
    {    0,  255, 255, false, 'ALPH', "Alpha"},
};

MVParamInfo *MyPlug::GetParamInfo(int Index)
{
    return &MyInfo[Index];
}

Parameters:
Param The index of the parameter in question.
Returns:
A pointer to an MVParamInfo structure providing details about the indicated paramter

MVPlug::GetParameter (  int  Index  )  [pure virtual]
 

MidiVid calls this function when drawing the knob shelf or saving the performance to retrieve the value of this parameter.

Parameters:
Index The index of the parameter in question.
Returns:
The value of the indicated parameter

MVPlug::SetParameter (  int  Index,
int  Value
)  [pure virtual]
 

Sets a new value for the indicated parameter. MidiVid calls this function in the following cases:

  • The user has moved the knob that your parameter is assigned to, changing its value.
  • The knob is associated with a continuous controller. In this case, the function will be called before every Tick() call.

Parameters:
Index The index of the parameter in question.
Value The new value of the parameter.

Member Data Documentation

MVPlug::Velocity
 

This member stores the velocity that the plugin was triggered at. Velocity is a value that corresponds to how hard the note was pressed, and ranges from 1 to 127. Zero velocity is used by MIDI to turn off the note, and is therefore not a possible value. The center value is 64, giving a range of +/- 63 off center.

Plugins are encouraged to allow the user to use velocity to affect the behavior of a plugin, as velocity is basically "free". Most low-cost MIDI keyboards support velocity. This value is only valid during NoteOn and Tick calls.

MVPlug::Channel
 

This member specifies which MIDI channel this instance of the plugin is assigned to. It is only useful if you wish to acquire continuous controller values yourself, using MidiVidInterface::GetControl(). This value is only valid during NoteOn and Tick calls.

MVPlug::StartChan
 

This is an internal value for MidiVid's use, and specifies which channels this plugin has been started on. If a patch is assigned to two or more channels at the same time, those channels will share the plugins from that patch. This value is a bit mask indicating which channels the plugin has been loaded on, and is used to prevent Startup() and Shutdown() from being called more than once.

The documentation for this class was generated from the following files:
MidiVid GPU Version 1.0
Copyright (c) 2005 Jason Dorie and VUTAG
Generated on: Sun Jan 25 23:45:41 2009