Esoteric Framework

3D basics

Abstract

Learn how to add 3D elements to your application.

Introduction

Before you can start adding 3D elements, three elements must be introduced.

<Application>
	<Scene3D id="scene">

	</Scene3D>

 	 <Camera3D id="camera" z="{-this.perfectDistance}" />

 	 <Viewport3D viewportWidth="{root.applicationWidth}" viewportHeight="{root.applicationHeight}" scene="{root.getElementById('scene')}" camera="{root.getElementById('camera')}" />
</Application>

• Scene3D is a collection of 3D elements
• Camera3D is a 3D camera with attributes such as the field of view
• Viewport3D is a 2D element depicting the scene as rendered through the camera

The values used for the attributes might look a little obscure at this point, but they will make more sense once you learn about expressions and bindings in later tutorials. For now, accept the fact that this will create a viewport with reasonable dimensions and a camera at a convenient location.

3D coordonate system

When working with 3D objects, the coordinate system is different than when dealing with 2D elements. The origin is located to the center of the viewport, as opposed to the top left corner. The x-axis is pointing to the right, the y-axis is pointing up, and the z-axis is pointing inside the screen. It may seem a little confusing at first, but it makes a lot more sense when working with 3D.

Using Sprite3D

The preview release only contains one 3D display object, called Sprite3D, but it is quite powerful. Simply put, it allows you to convert any 2D element to a 3D element. It is a 3D object which can have as many 2D children elements as you'd like. It is like a painting in space. To illustrate its use, we'll nest the buttons created in the 2D basics tutorial inside a Sprite3D, tweak its rotation a little, and add it to the scene.

Source Code

<Application>

	<Scene3D id="scene">
		<Sprite3D rotationX="10" rotationY="20">
			<Shape>
				<SolidFill color="0xCCCCCC">
					<Rectangle width="160" height="150" />
				</SolidFill>
			</Shape>
			<Sprite x="20" y="20">
				<Sprite>
					<Shape>
						<SolidFill color="0x222222">
							<RoundedRectangle width="120" height="30" ellipseWidth="10" ellipseHeight="10" />
						</SolidFill>
					</Shape>
					<TextField x="5" y="3" width="{this.textWidth}" height="{this.textHeight}" color="0xFFFFFF" size="16">Button 1</TextField>
				</Sprite>
				<Sprite y="40">
					<Shape>
						<SolidFill color="0x222222">
							<RoundedRectangle width="120" height="30" ellipseWidth="10" ellipseHeight="10" />
						</SolidFill>
					</Shape>
					<TextField x="5" y="3" width="{this.textWidth}" height="{this.textHeight}" color="0xFFFFFF" size="16">Button 2</TextField>
				</Sprite>
				<Sprite y="80">
					<Shape>
						<SolidFill color="0x222222">
							<RoundedRectangle width="120" height="30" ellipseWidth="10" ellipseHeight="10" />
						</SolidFill>
					</Shape>
					<TextField x="5" y="3" width="{this.textWidth}" height="{this.textHeight}" color="0xFFFFFF" size="16">Button 3</TextField>
				</Sprite>
			</Sprite>
		</Sprite3D>
	</Scene3D>
	
	<Camera3D id="camera" z="{-this.perfectDistance}" />
	
	<Viewport3D viewportWidth="{root.applicationWidth}" viewportHeight="{root.applicationHeight}" scene="{root.getElementById('scene')}" camera="{root.getElementById('camera')}" />
	
</Application>

Result

Conclusion

That's it! You now know how to display any 2D element in space. In the future, more 3D elements will be available, such as cubes, spheres, and other 3D primitives.