Vixen Plugin Development: Difference between revisions
No edit summary |
No edit summary |
||
Line 2: | Line 2: | ||
Although [[Vixen]] provides a standard set of [[Vixen_Plugins|plugins]] for a variety of hardware, individuals with different or custom hardware will need to develop their own plugin. Plugin development requires Microsoft Visual Studio, or another development environment for coding and compilation using Microsoft's .NET framework. | Although [[Vixen]] provides a standard set of [[Vixen_Plugins|plugins]] for a variety of hardware, individuals with different or custom hardware will need to develop their own plugin. Plugin development requires Microsoft Visual Studio, or another development environment for coding and compilation using Microsoft's .NET framework. | ||
==Example Source Code== | ==Vixen 2.0 & 2.5== | ||
In essence, all that is required to write your own output plugin for Vixen is to implement the <code>IEventDrivenOutputPlugin</code> interface (which also implies the <code>IOutputPlugIn</code> and <code>IPlugIn</code> interfaces.) | |||
The simplest way to do this is to first create a new C# Class Library (.dll) project. Next, you must add Vixen.exe as a Reference to your project, giving you access to the Vixen namespace, which you can use by adding "<code>using Vixen;</code>". After this, your class must inherit the <code>IEventDrivenOutputPlugin</code> interface. Finally, add the required functions to your class definition. In Visual Studio, function prototypes can easily be added for you by right-clicking <code>: IEventDrivenOutputPlugin</code> and selecting "Implement Interface > Implement Interface". | |||
===Interface Definition=== | |||
IEventDrivenOutputPlugin (Combined into one definition for clarity): | |||
<code> | |||
public interface IEventDrivenOutputPlugIn : IOutputPlugIn, IHardwarePlugin, IPlugIn, ISetup | |||
{ | |||
void Event(byte[] channelValues); | |||
//Called when the plug-in needs to update the hardware state during execution. | |||
// channelValues: Event values in channel order, 1 byte per channel. | |||
void Initialize(IExecutable executableObject, SetupData setupData, XmlNode setupNode); | |||
// Called anytime Vixen needs to make sure the plug-in's setup or other initialization is up to date. | |||
// Initialize is called before the plug-in is setup, before sequence execution, and other times. | |||
// It's called from multiple places at any time, therefore the plug-in can make no assumptions | |||
// about the state of the program or sequence due to a call to Initialize. | |||
// executableObject: An object which provides methods and fields which represent the | |||
// executable object (typically a sequence) which is executing. | |||
// setupData: A SetupData reference that provides some plug-incentric convenience methods. | |||
// It can be safely ignored. | |||
// setupNode: An XmlNode representing the root of the plug-in's setup data in the sequence. | |||
// Please see the Vixen.Xml class for some convenience methods. | |||
HardwareMap[] HardwareMap { get; } | |||
// Provide an array of the hardware resources this plugin is using. | |||
void Setup(); | |||
// Called when the user has requested to setup the plug-in instance. (Select COM Ports, etc) | |||
void Shutdown(); | |||
// Called when execution is stopped or the plug-in instance is no longer going to be referenced. | |||
// Vixen 2.0: | |||
List<Form> Startup() | |||
// Called when a sequence is executed. | |||
// Returns a list of forms that the plug-in needs to have injected into Vixen's MDI interface. | |||
// The previews are examples of plug-ins that return forms for this purpose. | |||
// Vixen 2.5: | |||
void Startup(); | |||
// Called when a sequence is executed. MDI forms are now handled differently. | |||
string Author { get; } // The author's name | |||
string Description { get; } // This plugin's description | |||
string Name { get; } // This plugin's name | |||
string ToString(); // Usually returns Name | |||
} | |||
</code> | |||
===Example Source Code=== | |||
The source code for the Elexol USB 24 I/O plugin is available [http://lights.onthefive.com/vixen-plugins here]. | |||
==Vixen 1.* (outdated)== | |||
===Example Source Code=== | |||
[http://www.vixenlights.com/downloads.html Source code] for the Parallel 12 plugin is available to assist plugin developers. The plugin is written in C# and works with Vixen 1.*. | [http://www.vixenlights.com/downloads.html Source code] for the Parallel 12 plugin is available to assist plugin developers. The plugin is written in C# and works with Vixen 1.*. | ||
Revision as of 08:02, 14 December 2009
Although Vixen provides a standard set of plugins for a variety of hardware, individuals with different or custom hardware will need to develop their own plugin. Plugin development requires Microsoft Visual Studio, or another development environment for coding and compilation using Microsoft's .NET framework.
Vixen 2.0 & 2.5
In essence, all that is required to write your own output plugin for Vixen is to implement the IEventDrivenOutputPlugin
interface (which also implies the IOutputPlugIn
and IPlugIn
interfaces.)
The simplest way to do this is to first create a new C# Class Library (.dll) project. Next, you must add Vixen.exe as a Reference to your project, giving you access to the Vixen namespace, which you can use by adding "using Vixen;
". After this, your class must inherit the IEventDrivenOutputPlugin
interface. Finally, add the required functions to your class definition. In Visual Studio, function prototypes can easily be added for you by right-clicking : IEventDrivenOutputPlugin
and selecting "Implement Interface > Implement Interface".
Interface Definition
IEventDrivenOutputPlugin (Combined into one definition for clarity):
public interface IEventDrivenOutputPlugIn : IOutputPlugIn, IHardwarePlugin, IPlugIn, ISetup
{
void Event(byte[] channelValues);
//Called when the plug-in needs to update the hardware state during execution.
// channelValues: Event values in channel order, 1 byte per channel.
void Initialize(IExecutable executableObject, SetupData setupData, XmlNode setupNode);
// Called anytime Vixen needs to make sure the plug-in's setup or other initialization is up to date.
// Initialize is called before the plug-in is setup, before sequence execution, and other times.
// It's called from multiple places at any time, therefore the plug-in can make no assumptions
// about the state of the program or sequence due to a call to Initialize.
// executableObject: An object which provides methods and fields which represent the
// executable object (typically a sequence) which is executing.
// setupData: A SetupData reference that provides some plug-incentric convenience methods.
// It can be safely ignored.
// setupNode: An XmlNode representing the root of the plug-in's setup data in the sequence.
// Please see the Vixen.Xml class for some convenience methods.
HardwareMap[] HardwareMap { get; }
// Provide an array of the hardware resources this plugin is using.
void Setup();
// Called when the user has requested to setup the plug-in instance. (Select COM Ports, etc)
void Shutdown();
// Called when execution is stopped or the plug-in instance is no longer going to be referenced.
// Vixen 2.0:
List<Form> Startup()
// Called when a sequence is executed.
// Returns a list of forms that the plug-in needs to have injected into Vixen's MDI interface.
// The previews are examples of plug-ins that return forms for this purpose.
// Vixen 2.5:
void Startup();
// Called when a sequence is executed. MDI forms are now handled differently.
string Author { get; } // The author's name
string Description { get; } // This plugin's description
string Name { get; } // This plugin's name
string ToString(); // Usually returns Name
}
Example Source Code
The source code for the Elexol USB 24 I/O plugin is available here.
Vixen 1.* (outdated)
Example Source Code
Source code for the Parallel 12 plugin is available to assist plugin developers. The plugin is written in C# and works with Vixen 1.*.
Modifications are required for the plugin to work with Vixen 2.0:
- Change the
Parallel12
class to implement theIEventDrivenOutputPlugIn
,IOutputPlugIn
,IPlugIn
interfaces instead of thePlugIn
interface. - Change the first parameter of the the
Initialize
toIExecutable executable
. TheList<Channels> Channels
property ofIExecutable
can be used in place of theChannel[] channels
parameter. - In the
get
method for theHardwareMap
property, change the call tonew HardwareMap
to pass the string constant"Parallel"
as its first parameter. The enumerationPortType
no longer exists.
Resources
- Programmer's Guide (Only for Vixen 1.*)
- Example Source Code (Only for Vixen 1.*)