Wiki Page Comments  

DX Studio SDK

For C++ developers the SDK provides a way to interface your own C++ processing or rendering code into the engine.

This is achieved by building a '.dxeffect' file.

A valid .dxeffect plugin file is ZIP compatible, and contains all the resources that it needs in the single file. It also contains a DLL (named plugin.dxpp) that provides the hooks into the player.

Here is a sample plugin as a Visual Studio 2008 project. Player SDK Sample

You will need DX Studio v3.2.47 or later to run any plugins you build with this SDK.

By compiling this project, it will build the DLL and then launch the ZIP application to bundle all the files (including the DLL) in the ./pack subdirectory into a dxeffect file. See the buildpack.bat file for more information.

To get your own plugin up and running fast, we recommend copying the entire plugin sample directory DXStudioPlayerPluginSample and just renaming the copy to your own name. All the paths are relative, so this shouldn't cause any errors.

The description of the properties and methods supported by this dxeffect are stored in a file called 'header.xml'. If you find this in the Solution Explorer and double click it, you will see how the plugin is described. It is also useful to provide a thumbnail (usually called 'thumbnail.jpg') that gives a 128x128 full colour image for the editor to display as an icon for the plugin.

Contents

Header File

This is a sample header.xml file for a plugin:-

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>

<!-- DX Studio Player Plugin Description -->

<!-- Identification (version here is for the file format -

set your version in the version node) -->

<dxeffect version="4.0.0" name="Sample Plugin" id="sample">

<copyright>No copyright, use as you like!</copyright>

<!-- Here you can describe the plugin -->

<summary>

<![CDATA[ A sample plugin that is a good starting point for building your own.]]>

</summary>

<!-- A 128x128 thumbnail for the plugin -->

<thumbnail src="thumbnail.jpg" />

<!-- Use a GUID generator to set your own GUID here

(DXS can generate a suitable one in the Network settings page) -->

<version id="{b2bda7a1-9a9f-4d0f-99d0-f7ba5d4ba007}" friendlyversion="1.0.5" />

<!-- The DLL - the lowest try orders are attempted first -->

<plugin tryorder="0" src="plugin.dxpp" />

<!-- Where does the plugin apply? Any number application entries with type set to:

scene3d, scene2d, object3d, object2d, effectpoint3d, effectpoint2d,

effectplane3d, effectplane2d, effectcube, material -->

<application type="scene3d" />

<application type="scene2d" />

<!-- Notify types are 'updatebegin' 'updateend' for the start/end of the update, 'renderbegin'

and 'renderend' for start/end of the render, 'renderscenebegin' 'rendersceneend'

for the rendering of a scene. 'renderprepare' is called once before any other render calls. -->

<!-- For renderscene begin/end/object you can specify passes.

0 is the normal pass, -1 the pass before, 1 the pass after (comma separate multiple passes) -->

<notify type="updatebegin" />

<notify type="updateend" />

<notify type="renderprepare" />

<notify type="renderbegin" />

<notify type="renderend" />

<notify type="renderscenebegin" passes="0" />

<notify type="rendersceneend" passes="0" />

<notify type="rendersceneobject" passes="0" />

<!-- Now define any properties and methods you want to expose to the editor -->

<method id="reset"

help="reset//A sample function called 'reset' that resets the rotation of the overlay." />

<property id="speed" type="float"

help="speed//A float multiplier for the speed of rotation of the overlay." default="1.0" />

</dxeffect>

All description of the effect should be in the dxeffect block. The dxeffect version should always be 4.0.0 for this SDK, the name is the 'friendly' name of the effect that can contain punctuation and spaces, and the id is the JavaScript name that must start with a letter and only contain letters, numbers or underscores.

Inside the dxeffect, the 'application' tag describes where the effect can be used, either on a document, scene or individual object.

The 'notify' tags determine when the plugin is called in the update/render pipeline. The attribute 'passes' is a comma separated list of which passes the effect is interested in. For example "-1,0" would mean the effect would want to be called once before the main draw occurs, and again on the main draw.

The 'summary' tag describes in detail what the plugin does in a CDATA block (so you can use any punctuation without restriction).

Methods that the plugin uses are listed with the 'method' tag. Use the 'help' attribute to give the context sensitive editor information on what to display.

The help string starts with the syntax, and follows with the description after a double forward slash. e.g.

myMethodName//Does something cool!

Properties work in the same way as methods, except they also contain a type. The type can be one of string, bool, int or float. You can also supply a 'default' attribute which contains the default value the editor should use.

Compiling and Using

TraceMonkey

The system links in to TraceMonkey (the JavaScript engine used by DX Studio). You can extend the properties and methods of your JSClass as you need. The headers and a Visual Studio 2008 lib are provided in the SDK under the js subfolder.

DirectX SDK November 2008

The DX Studio Player uses the Novermber 2008 SDK, which links to D3DX9_40.DLL. By using the same SDK you can be sure the D3DX library will be available.

You can download and install the SDK from the following link:-

DirectX SDK November 2008

Editing the Sample

The bulk of the plugin work should be done in the myclass.cpp file (you can rename the class or source files as you like). Access to the player information you need can be found in the global pInfo structure, and further engine information is passed in the SEngineInfo structure to a EngineStage callback.

You will need to edit buildpack.bat to make sure it names your dxeffect correctly and puts it in the right place.

In the sample, the myclass.cpp loads and draws a simple sprite over the top of the contents of the scene the effect is attached to. To test, compile the project then launch DX Studio (making sure buildpack.bat is copying the result to the right directory). Create a new 3D scene and go to the Scene Properties. In the Effects tab, add the sample effect in and hit preview. The plugin will then be launched. Try setting the 'speed' property in script (scene.effects.mysample.speed=2.0) to see how it now integrates into the editor.

New - multidevice capability. If you want to run on multiple devices (e.g. an edge blending projector setup), you can make your plugin multidevice aware. If you set the info (see the sample) to declare support for this, the player will call your Init function for each device, passing a different deviceindex. You should check this deviceindex to determine where to create then read all device resources.

The sample document in the root folder shows the sample plugin embedded. Note: For development it can be much quicker to edit the scene and make the dxeffect file an explicit external link to the dxeffect in your library folder. Then you don't need to re-save the test document to try out changes.

Last edited by Chris S on Thursday, September 23, 2010