HowToMakeADashPlugin
From Dash
Contents |
How to make a Dash plugin RenderEngine for SCREM
Overview
You can create a plugin (A Cocoa Bundle) that Dash will load at runtime, and can register itself with Dash as a RenderEngine that works with SCREM. When SCREM asks for this RenderEngine, Dash will instantiate an object of your plugin's primary class, and insert it into Dash's scene graph.
I recommend that after you read this page, you look at the SphereDraw example plugin, and the Dash ScremNode class.
Look at this page if you need more information about Objective-C or Cocoa.
Install Dash
You will need to install Dash. Here is a page with installation instructions.
Create an Xcode Project
Create an Xcode Project to build a Cocoa Bundle. We have an Xcode Template that makes it easy to create a new Plugin project. User defined Xcode templates are placed in a templates folder called ~/Library/Application Support/Developer/Shared/Xcode/Project Templates. If that doesn't exist, create that folder.
cd ~
mkdir -p "Library/Application Support/Developer/Shared/Xcode/Project Templates"
Download the RenderEngine Xcode template Media:RenderEngineTemplate.zip. Move the RenderEngine directory into the templates folder. The next time you start Xcode, you can choose File->New Project, and you'll find a RenderEngine template in the New Project Assistant. In Xcode 3.1 it will be found in the User Templates section.
Xcode project setup
If you use the DashPlugin template, the only project setup you need to do is to set the DASH_DIR build settings variable.
- Click the disclosure triangle for Targets.
- Right click the project target, and choose "Get Info".
- Click the Build tab.
- Make sure that the Configuration popup menu is set to Debug
- You can find it at the very bottom of the list in the User-Defined section. Change this value to be the directory that contains the Dash source project. (ie. the folder where you can find the Dash.xcodeproj file.)
Also, make sure that your active build configuration is set to Debug. Currently, this setting should always be Debug. (Also true if you are building Dash.)
Plugin Principal Class
Your plugin must define one principal class. You may create multiple classes in your plugin, but there can only be one principal class. Note that the names of any classes you create must be unique within Dash. Objective-C has a flat namespace. In our example above, the Principle Class is called CubeDraw. The CubeDraw class is defined in CubeDraw.h and CubeDraw.m. Notice that we set the PrincipleClass name in the Info.plist file.
Your principal class should be subclassed from the class ScremNode. (see the header file smallab/ScremNode.h in the Dash project.)
Plugin loading
When Dash starts, it will search the PluginManager search path for Cocoa Bundles that implement the DashPluginProtocol formal protocol, and load those bundles. The search path is a string that may list mulitple folders to search, with : separators. The search path can be modified in the Preferences Panel (Dash->Preferences), in the General tab. Any change you make to the search path will take effect the next time you launch Dash.
For example, let return to our CubeDraw example. if I set the search path to "/Users/Shared/Dash/plugins", then I should copy or move the CubeDraw.bundle from build/Debug to the /Users/Shared/Dash/plugins directory. Then, the next time I start Dash, in the Xcode Debugger Console, I will see Dash finds the plugin and loads it:
INFO , PluginManager.m:104 | search folder "/Users/Shared/Dash/plugins" for plugins
DEBUG, PluginManager.m:111 | loadResource: "/Users/Shared/Dash/plugins/CubeDraw.bundle"
DEBUG, PluginManager.m:66 | loading plugin: "/Users/Shared/Dash/plugins/CubeDraw.bundle"
INFO , PluginManager.m:72 | found principal class "CubeDraw"
2007-12-19 11:40:14.398 Dash[21021:10b] initializePlugin CubeDraw
INFO , Screm.m:93 | added Screm renderEngine "CubeDraw"
When your plugin (bundle) is loaded, the class method:
+ (BOOL) initializePlugin:(NSBundle *)bundle
will be called on your principal class. This method provides an opportunity for you to do any one time plugin initialization that you might require. In this method, you must notify Dash's Screm controller about your RenderEngine by sending the addRenderEngine:class: message.
[[Screm screm] addRenderEngine:@"SphereDraw" class:[SphereDraw class]];
The first arguement (in this example @"SphereDraw" is the SCREM name of your RenderEngine. This name must be a unique name for a RenderEngine in Dash. If Dash already has a RenderEngine loaded with the same name, it will not load your RenderEngine.
RenderEngine initialization
When the Dash Screm controller recieves a create message with the name of your RenderEngine, it will instantiate an instance of your class. It will send a (factory) message to your class:
+ (id) createWithName:(NSString *)aName parent:(Node *)aParent
This method is implemented by the ScremNode class, and it won't normally need to be overriden. The factory method will then create an instance of your class, calling your initializer:
- (id) initWithName:(NSString *)aName parent:(Node *)aParent
Your initializer should first call its super initalizer.
if (![super initWithName:aName parent:aParent]) {
logError( @"SphereDraw, super init failed!" );
return nil;
}
Then you may do any object initialization that your RenderEngine requires.
Drawing
Each time Dash draws a frame, it will call your object's drawShape method:
- (void) drawShape:(GraphicsState *)state
Inside this method you can use any OpenGL or Dash methods to perform drawing.
Screm Attributes
When the Dash Screm controller recieves an attribute message for your object, it will will send a message to your object using the Key Value Coding technique. For example, the SphereDraw plugin handles a screm attribute called "radius". It does this by implementing two methods - a "getter" and a "setter":
- (float) radius {
return radius / [screm scremToDashScale];
}
- (void) setRadius:(float)value {
radius = value * [screm scremToDashScale];
}
Screm mediaobject messages
When the Dash Screm controller recieves a mediaobject message for your object, it will send the message to your object:
- (void) mediaobject:(NSString *)value forKey:(NSString *)attribute
See the SphereDraw plugin for an example of recieving a mediaobject message, and using it as a reference for a texture map.
Screm text_message messages
When the Dash Screm controller recieves a text_message message for your object, it will send the message to your object:
- (void) textMessage:(NSString *)value forKey:(NSString *)attribute
Deallocation
When your object is destroyed, it will received a dealloc message. This method allows you to release any storage your object has allocated.
More Information
...... this section is a work in progress .....
More information about how Dash renders a frame.
Regarding Dash Materials.
Regarding using OpenGL Shading Language.
