Architectural Overview

Emma is an open, extensible rich media runtime for the Web.

Emma's Content Development Kit (CDK) supports content artists using declarative markup and creative tools to produce new user experiences. It includes tools, documentation and examples which facilitate production of content to be performed using the Emma runtime engine.

Refer to Emma's Software Development Kit (SDK) for C++ programmers who want to develop new Emma extension modules, develop Emma-based applications, or to extend or modify the core Emma source code.

Declarative Markup

Emma's .ema file format provides an uncluttered declarative scene markup format, which describes a set of multimedia Objects (known as Nodes) and establishes the relationships between those Nodes. Each Node presents its interface as a set of Fields; these Fields are used to set and alter the properties which control the Node's behavior. This unifying Node/Field architecture gives Emma the flexibility for extension into a wide range of composable media, interactivity, and behavioral domains. The current set of predefined Nodes, Fields, and other useful Objects is documented in this guide (see Class List above).

For example, the .ema markup below presents a 3D teapot on the screen.

	#Emma V0.3 utf8 lua

	Shape {
		scale 0.05 0.05 0.05
		material Material {
			diffuse Color.red
		}	
		geometry MeshInline {
			url "teapot.mesh"
		}
	}

The first line is the .ema markup header, required to read this file format. This simple scene includes a Shape node; its scale field assigns small x,y, and z scale factors to reduce the size of the model it contains. A Material node is assigned to the Shape's material field, with its diffuse color component set to draw the model red. Finally, a MeshInline node is assigned to the Shape's geometry field. The MeshInline reads in the teapot model described by the mesh geometry contained in the binary file "teapot.mesh." This mesh file was exported from 3D Studio Max, a commercial modelling and animation application.

The .ema file format provides a simple, human readable syntax for describing Emma's objects. However, .ema will be directly translatable into its companion XML syntax, .xma, and back again, to afford content production and generation efforts with the programmable power of XML. .xma translation is slated for development as part of Emma's content authoring framework.

For example, the .xma markup below presents the same 3D teapot on the screen.

	<?xml version="0.3" char="utf8" script="lua"?>

	<node type="Shape">
		<field name="scale"> 0.05 0.05 0.05 </field>
		<field name="material"> <node type="Material">
			<field name="diffuse"> <object type="Color" property="red"> </field>
		</node>	
		<field name="geometry"> <node type="MeshInline">
			<field name="url"> teapot.mesh </field>
		</node>
	</node>

Nodes and Prototypes

XXX to come

Fields and Events

Whenever you make an assignment to a Field that is contained in an Emma Node, it has the ability to generate an event. An event is simply a Lua function that gets called whenever the Field value is set. These functions have access to the same global variables as any Lua function in Emma. Additionally, it has access to a self variable, which is the Node containing the field that fired, and to the TOP variable, which is set to the Prototype instance containing that Node.

The Emma language supports routing syntax and function syntax for adding events to Fields. It looks like this:

	field SFFloat myval 	DO { print("myval is set to ",self.myval) }
				TO OTHERNODE.otherval<BR>


	Timer { fraction DO { print("fraction is set to ",self.fraction) }

The first two lines set events on a Field being declared as a top-level interface in a Prototype. The last line adds an event to the Field of a Node instance. Note that you can have more than one event on a Field. The function associated with each is called in the order in which it appears in the markup.

Emma routing allows a convenient shorthand for defining simple connections between Fields. In the same way you can use the DO syntax to place a function on a field, you can use the keywords TO and FROM to specify a destination (in the case of TO) or source (in the case of FROM) for an event. You can also use a separate ROUTE statement, where you specify both the source and destination of the event. Routing in Emma is handled using Lua function calls. These 3 statements:

	fraction TO OTHERNODE.fraction
	DEF T Group { translation FROM INTERP.value }
	ROUTE MOUSE.pos TO CONTROL.pos

each create a small Lua function that looks like this:

	fraction.addEvent(function(self) TOP.OTHERNODE.fraction = self.fraction end)
	TOP.INTERP.value.addEvent(function(self) TOP.T.translation = TOP.INTERP.value end)
	TOP.MOUSE.pos.addEvent(function(self) TOP.CONTROL.pos end)

So all the same rules apply to routes as to DO scripts.

Events are added to a field with the addEvent function, like this:

	local i = T.fraction.addEvent(function(self) print("fraction is ",self.fraction) end)

addEvent returns an index number which can be used to later remove that event like this:

	T.fraction.removeEvent(i)

Page Communication

On the containing page, a call in to an instance of the plugin object named MyEmma looks like this:

	MyEmma.call("bar", 1.5)
	

This is received within the Emma content using a script like this:

	page.bar = function(a)
		print("handling function bar with argument a");
	end
	

From inside the Emma content, a call out to the containing page looks like this:

	page.call("foo", "hello", 2.7)
	

This is received on the containing page using a Javascript function like this:

	function foo(a,b) {
		print("handling function foo with arguments a and b");
	}
	

Resources

The Emma runtime engine can be controlled by a number of resource settings. These control setting properties are found on the top level system object "root". Script developers can get and set the value of these properties at runtime, and several configuration files can be used to initialize the values of these properties at startup. These configuration files include:

• init.lua is compiled into the Emma engine when it is built, and establishes default values for all runtime configuration settings.
• local.lua is an optional file which may be placed in the same directory where the Emma engine executable is located. In typical usage, platform-specific settings are distributed to this location, to establish appropriate default values for all invokations of the engine from this location.
• app.lua is an optional file which may be placed in the same directory where a main content file is located. In typical usage, application-specific settings are distributed to this location, to establish appropriate default values for all invokations of the content launched from this location.

root

The root resource contains high level properties used to control Emma's runtime environment. These include:

            root.rendererType = "DIRECT3D9";

Parameters:

rendererType

sets the low-level graphics rendering subsystem to be used. Possible values are "DIRECT3D7", "DIRECT3D9", or "OPENGL". Default value: "DIRECT3D9"

root.settings.log

The root.settings.log resource contains detailed settings used to control logging output in Emma's runtime environment. These include:

            root.settings.log.level = "INFO";
            root.settings.log.file = false;
            root.settings.log.screen = true;
            root.settings.log.screenX = 0;
            root.settings.log.screenY = 0;
            root.settings.log.screenWidth = 550;
            root.settings.log.screenHeight = 350;
            root.settings.log.network = false; 
            root.settings.log.networkPort = 444; 
            root.settings.log.graphicsLogFile = false;

Parameters:

	log.level	sets the level of message traffic output to the log file. Possible values are "NONE", "ERROR", "INFO", or "DEBUG". Default value: "NONE"
	log.file	specifies whether message output will be sent to the log file. Default value: false
	log.screen	specifies whether message output will be sent to the screen console. Default value: true
	log.screenX	specifies the horizontal location of the screen console on the display. Default value: 0
	log.screenY	specifies the vertical location of the screen console on the display. Default value: 0
	log.screenWidth	specifies the width of the screen console on the display. Default value: 550
	log.screenHeight	specifies the height of the screen console on the display. Default value: 350
	log.network	specifies whether message output will be sent to the network. Default value: false
	log.networkPort	specifies the network port opened for message output. Default value: 444
	log.graphicsLogFile	specifies whether graphics subsystem message output will be sent to a graphics log file. Default value: false

XXX references from other sections of the Guide follow:

---