Developer Home Page - magic-lantern-studio/mle-documentation GitHub Wiki

Welcome to the Magic Lantern Developer Wiki. This tool is used to provide documentation concerning the development tasks and methodologies for the Magic Lantern project. Here you can find reference to valuable information concerning Magic Lantern development tasks.

Table of Contents

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 for Windows 7/8/10 platforms. The GNU g++ and autoconf development environments are used to build the C++ libraries for Linux platforms. The Java JAR packages are currently built using the Eclipse development environment. An Android solution has also been developed and can be built using Android Studio.

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

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 7 platforms.

Dependencies

The Rehearsal Player has the following dependencies:

  1. Coin library, version 4.0.0. You can download the library from coin.
  2. SoWin library, version 1.5.0. You can download the library from SoWin.
  3. simage library, version 1.8.0. You can download the library from simage.
  4. FreeImage, version 3.18.0. You can download the library from FreeImage or build it from the Magic Lantern project, freeimage.
  5. Microsoft Visual Studio 2017. Note that project workspaces are available for Microsoft Visual Studio 2010, Microsoft Visual Studio 2005 and Visual Studio 6; however, Wizzer Works will no longer support the VC6 tool chain and support for VS 2010 and VS 2005 is deprecated.
Build Instructions

The Rehearsal Player is built upon Silicon Graphics Open Inventor technology. It currently uses the Coin library, 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 4.0.0 of the Coin library will soon be available. For now, the modifications can be tracked here:

The Rehearsal Player can be built for the Microsoft Windows 7 platforms using the following environment:

Mastering Tools

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

  • gentables - generate the Title runtime tables
  • gengroup - generate the Title Actor Groups
  • genscene - generate the Title Scenes
  • genmedia - generate the Title Media References
  • genppscript - generate the Digital Playprint build script
  • gendpp - generate the Digital Playprint
  • genmakefile - generate the Title Makefile
  • dumpgroup - Dump the contents of the Actor Group Chunks
  • dumpscene - Dump the contents of the Scene Chunks
  • dumpmedia - Dump the contents of the Media Reference Chunks
  • dumpdpp - Dump the contents of the Digital Playprint

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

Multiple Build Environments

It is possible to use multiple build environments in parallel (i.e. Linux autoconf build env and Linux Qt Studio build env). To do this, setup separate MLE_HOME directories and switch between them using a shell function.

[!Note] These environment variables need to also be configured in the respective IDEs (e.g. Eclipse, Qt Studio)

Linux autoconf Environment

The following is a bash shell function for setting up an Eclipse autoconf build environment.

function mlestudioenv () {
    echo "Setting Magic Lantern Studio Environment"
    echo "    Use Eclipse IDE and autoconf build environment,"
    echo ""

    export MLE_HOME=/media/workarea/msm/Projects/WizzerWorks/MagicLanternStudioHome
    export MLE_ROOT=/opt/MagicLantern
    export MLE_WORKPRINTS=$MLE_ROOT/include/workprints
    unset QT_CC

    echo "    MLE_HOME = $MLE_HOME"
    echo "    MLE_ROOT = $MLE_ROOT"
    echo "    MLE_WORKPRINTS = $MLE_WORKPRINTS"

    cd $MLE_HOME
}

Linux Qt Studio Environment

The following is a bash shell function for setting up a Qt Studio build environment.

function mleqtenv () {
    echo "Setting Magic Lantern Python Environment"
    echo "    Use Qt Studio and qmake build environment."
    echo ""

    export MLE_HOME=/media/workarea/msm/Projects/WizzerWorks/MagicLanternQtHome
    export MLE_ROOT=/opt/MagicLantern
    export MLE_WORKPRINTS=$MLE_ROOT/include/workprints
    export QT_CC=Qt_5_12_11_GCC

    echo "    MLE_HOME = $MLE_HOME"
    echo "    MLE_ROOT = $MLE_ROOT"
    echo "    MLE_WORKPRINTS = $MLE_WORKPRINTS"
    echo "    QT_CC = $QT_CC"

    cd $MLE_HOME
}

Windows 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:

Testing the BRender Target

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

Testing the Rehearsal Player

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