In this article, we'll take a look at ScriptENGINE Extensions and how they can be used in your programs.

ScriptENGINE extensions (or plugins) are are specifically designed for use with the ScriptENGINE. They are built as Dynamic Link Libraries (DLLs) and loaded into your programs using the IApp:loadExtension() function.

After loading an extension a new interface will usually be added to the ScriptENGINE. The Programmer's Reference contains all the details for every published ScriptENGINE extension deployed with the ScriptENGINE Runtime.

View the Demo Code

The Demos are included in the ScriptENGINE SDK. Now's a great time to get the ScriptENGINE SDK from our website (including the SciTE code editor, Programmer's Reference and ScriptENGINE Demos).

Navigate to the ScriptENGINE SDK/[Extensions] Using AVIs, ZIPs and COM via extensions folder for the example.

Open the world.e76script in the SciTE code editor. We will be referring to the world.e76script for the rest of this article.

The ScriptENGINE Demo Framework

The ScriptENGINE Demos are run using the runDemo.e76script framework code in the ScriptENGINE SDK/Demos folder.

Loading an Extension

Note that we will be focusing on the AVI Extension for this article.

Extension is loaded into the engine using:

extAVI = IApp:loadExtension(IApp:getExeFilePath() .. './Extensions/extavi.dll')

• The extavi.dll is supplied as part of the ScriptENGINE Runtime distribution. The extAVI return value is later used to unload the extension. You can also check the return value to make sure that the extension was successfully loaded into the ScriptENGINE.

Unloading an Extension

When you're finished, you can unload an extension.

Extension is unloaded into the engine using:

IApp:unloadExtension(extAvi)

Alternatively, you can leave an extension loaded for the entire lifetime of your program. When your program exits, all extensions will be unloaded.

The CAVIReader Utility Script

After loading the AVI extension, the IAvi interface is available from your code. It's described in more detail in the Programmer's Reference.

The ScriptENGINE SDK also includes a utility class called CAVIReader in the Scripts folder. It can be loaded into your scripts using:

IApp:loadScript('CAVIReader')

More info about the CAVIReader class is included in the script. The CAVIReader class simplifies access to the IAVI interface. You don't have to use it and can call the IAvi interface functions directly if you like.

Playing an AVI using the IAvi Interface and CAVIReader Class

Create a new AVI reader by creating a CAVIReader:

aviReader = CAVIReader:create('demointro.avi')

• demointro.avi is the AVI filename to load.
• aviReader is the new CAVIReader instance.

Checking the AVI file opened successfully:

aviReader:isOpen()

Creating a new graphics texture to write the AVI data into:

IGraphics:createTexture('aviTexture', '256 256', COLOR_FORMAT_A8R8G8B8)

• aviTexture is our user-defined name for the new texture. This name can be used anywhere in the graphics engine where an image filename would normally be used.You can apply them to 3D entities or 2D GUI controls.
• '256 256' is the requested texture size in pixels. You should keep these dimensions to a factor of 2 (eg. 2,4,8,16,32,64,128,256,etc) to utilise the graphics hardware.
• COLOR_FORMAT_A8R8G8B8 is a constant defined in the constantsColorFormat.e76script included in the ScriptENGINE Runtime distribution.

Create a GUI image that uses the new texture:

IGraphics:createImage('aviImage', 'aviTexture', IMisc:rectCreate(left, top, 1, 1), false, false)

• aviImage is the name of the new GUI image control added to the graphics engine.
• aviTexture is the name of the texture we created. Normally this would be a filename for an image on disk.

Play the AVI:

aviReader:play('aviTexture', false, 'extAVIComplete')

• aviTexture is the user-defined texture we want the AVI data to be written in to.
• extAVIComplete is the name of a global Lua function to call when the AVI completes. The CAVIReader will call this function the the AVI completes.

The ScriptENGINE Programmer's Reference

We recommend reading the IAvi Interface in the Programmer's Reference.