Developer_Documentation

Note

This wiki information has been deprecated. Please visit Magic Lantern Studio Github wiki for current information.

---

Developer Documentation

This page provides a reference to valuable information concerning Magic Lantern development tasks.

• Developer Documentation
  • Build Instructions
    • Magic Lantern SDK Components
    • Magic Lantern Studio Components
      • Rehearsal Player
        • Dependencies
        • Build Instructions
      • Mastering Tools
      • Magic Lantern Studio IDE
        • Magic Lantern Java2D Studio IDE Build Environment
        • Magic Lantern Android Studio IDE Build Environment
        • Magic Lantern DirectX Studio IDE Build Environment
    • Build Notes
  • Testing Magic Lantern
    • Testing the Java2D Target
    • Testing the Android Target
    • Testing the BRender Target
    • Testing the Rehearsal Player

Build Instructions

The Magic Lantern components are currently developed using the C++ and Java programming languages. This section describes how to build the components for the various technologies targeted by the Magic Lantern SDK and tool chain.

Magic Lantern SDK Components

The Magic Lantern Software Development Kit is comprised of a Runtime Engine and components, or parts, that are used to construct the application title. These parts are called Actors, Roles, Sets, Stages and Mediarefs.

An Actor is the basic unit of action and presentation within a title. A Role is the software module that handles the actors platform-dependent presentation on a set. A Set is an abstract view of a collection of actors that are presented on a stage. A set is used to manage a presentation, such as a 3D scene-graph or 2D windowing environment. The Stage is a collection of services on the target platform, such as rendering, input, sound, physical modeling, proximity and collision detection, and event handling. The stage, set, and role are the platform specific components in a Magic Lantern title. The actor is a platform independent component in a Magic Lantern title. Finally, a Mediaref is an object used to reference the representation of media across multiple platforms. It is currently a pointer to an outside media file, such as a graphics image or an audio file.

The Magic Lantern SDK is currently available as native C++ libraries as well as Java JAR packages. The C++ code base can be built using Microsoft Visual Studio 2010. Work is also underway to provide solutions using GNU g++ development environments for Linux. The Java JAR packages are currently built using the Eclipse development environment. An Android solution has been developed and can be built using Android Studio.

The following links can be used to build the supported targets:

• SDK Build Environment using Microsoft Visual Studio
• SDK Build Environment using Microsoft MSBuild
• SDK Build Environment for Linux Platform
• SDK Build Environment for J2SE Platform
• SDK Build Environment for Android Platform

---

Magic Lantern Studio Components

The Magic Lantern Studio is the collection of tools used to help build and deploy Magic Lantern titles. It is comprised of authoring tools used in the construction and rehearsing of the title. The Magic Lantern Studio also provides tools to facilitate mastering to specific device targets (i.e. Java2D, Android, J2ME).

The Magic Lantern Studio is comprised of the following tools:

• Rehearsal Player
• Mastering Tools
• Magic Lantern Studio IDE

Rehearsal Player

The Magic Lantern Rehearsal Player is a tool used to rehearse a Digital Workprint. The user can exercise a Magic Lantern title using the Rehearsal Player without mastering the title to a specific target. The player currently runs on the Microsoft Windows XP and Vista platforms.

Dependencies

The Rehearsal Player has the following dependencies:

1. Kongsberg SIM's Coin library, version 1.3.1. You can download the library from Coin3D.
2. Kongsberg SIM's SoWin library, version 1.5.0. You can download the library from Coin3D.
3. Kongsberg SIM's simage library, version 1.7.0. You can download the library from Coin3D.
4. FreeImage, version 3.15.0. You can download the library from FreeImage.
5. Microsoft Visual Studio 2010. Note that project workspaces are available for Microsoft Visual Studio 2005 and Visual Studio 6; however, Wizzer Works will no longer support the VC6 tool chain and support for VS 2005 is limited.

Build Instructions

The Rehearsal Player is built upon Silicon Graphics Open Inventor technology (http://en.wikipedia.org/wiki/Open_Inventor...). It currently uses Kongsberg SIM's Coin library (<http://www.coin3d.org/>), an independent implementation of the API. Wizzer Works has made some minor modifications to the Coin implementation to facilitate new UI components, SoTransformer2Dragger and SoTransformer2Manip. A patch identifying these modifications for version 3.1.3 of the Coin library will soon be available. For now, the modifications can be tracked here:

• Coin 3.1.3 Modifications
• Building Coin

The Rehearsal Player can be built for the Microsoft Windows XP and Vista platforms using the following environment:

• Rehearsal Player Build Environment using Microsoft Visual Studio

Mastering Tools

The Magic Lantern mastering tools are used to generate a Digital Playprint and code for the target platform. Theses tools include:

• gentables
• gengroup
• genscene
• genmedia
• genppscript
• gendpp
• genmakefile
• dumpgroup
• dumpscene
• dumpmedia

Magic Lantern Studio IDE

The Magic Lantern Studio IDE is an integrated development environment used to develop, test and debug Magic Lantern titles. The IDE is built upon the Eclipse open source platform and is comprised of a collection of plug-ins and tools that have been compiled for the Microsoft Windows platform.

The Magic Lantern plug-ins for Eclipse are packaged together so that they address the needs for particular Magic Lantern targets. For example, some of the plug-ins target Java SE and Java2D titles, while other plug-ins are designed for building Android applications. The following Magic Lantern IDE configurations are under development:

• Magic Lantern Java2D Studio IDE
• Magic Lantern Android Studio IDE
• Magic Lantern DirectX Studio IDE (TBD)
• Magic Lantern BRender IDE (OBSOLETE)

Magic Lantern Java2D Studio IDE Build Environment

The Java2D Studio IDE is used to build Magic Lantern titles targeting the Java SE and Java2D platform.

To build this tool chain, please follow these instructions: IDE Build Environment for Java2D Studio.

To build the Magic Lantern Java2D Studio distribution package, first follow the above instructions for the IDE Build Environment for Java2D Studio. Then create the product using the following instructions: Java2D Studio Product Build Instructions.

Magic Lantern Android Studio IDE Build Environment

The Android Studio IDE is currently used to build Magic Lantern titles targeting the Google Android platform.

Earlier efforts were based on the Eclipse IDE (also called Android Studio). To build this tool chain, please follow these instructions: IDE Build Environment for Android Studio.

Magic Lantern DirectX Studio IDE Build Environment

TBD

---

Build Notes

• Microsoft Visual Studio 2005 Notes
• Turn off the Microsoft UAC. These build instructions are based on using mapped network drives ("M:") in Microssoft Windows. If you are building on the Vista and Windows 7 platforms, you will probably run into issues with the post-build events that copy the header files and binaries to $MLE_HOME. You will most-likely see errors about an "Invalid drive specification". This is the Windows UAC (User Account Control) getting in the way (for more information, see this article).
• Create a MSBuild .proj file. To create a Microsoft build project (MSBuild) from a Microsoft Solution file (.sln), use the following directions. If the solution builds successfully, an addition MSBuild .proj file is created (this is the file that MSBuild creates internally to process .sln files).
  • cd directory location of Solution file
  • set MSBuildEmitSolution=1
  • msbuild <your project>>.sln
• Turn off parallel builds. Visual Studio will attempt to build projects in parallel if you hav a multi-processor computer. This may cause problems with temporary locked files. Turning off parallel builds seems to fix most things. Go to Tools->Options->Project and Solutions->Build and Run. Then set maximum number of parallel project builds to 1.

Testing Magic Lantern

This section discusses how to test the various Magic Lantern technologies.

To test the Magic Lantern SDK, several titles have been developed to exercise the Java and C++ APIs.

Testing the Java2D Target

The following titles may be used to test the Magic Lantern Java2D Target:

• HelloWorld Title for Java2D
• DPP Image Test Title for Java2D

Testing the Android Target

The following titles may be used to test the Magic Lantern Android Target:

• Image Test Title
• Cube Test Title
• Model Test Title
• HelloCube Title

Testing the BRender Target

The following titles may be used to test the Magic Lantern BRender Target:

• Moving Teapot Demo for BRender

Testing the Rehearsal Player

The following titles may be used to test the Magic Lantern Rehearsal Player:

• Null Title for Rehearsal Player
• Moving Teapot Title for Rehearsal Player