Table of Contents
Euclid is the API package that allows you to integrate the Dynamic Perspective UI into your apps. The Euclid API is Amazon's toolkit of controls, containers, and convenience classes that you can use to add 3D effects to your app. If you are new to developing 3D apps or to Euclid, this page helps familiarize you with the concepts and terminology used by Euclid.
What does "3D" Mean in the Amazon Context?
The term "3D" can mean different things, depending on the context. For example, when you hear the term "3D" you might ask yourself, "Do my users need special glasses to view my app correctly?"
In the context of Amazon's 3D effects, no special glasses are required. In Euclid-based development, 3D means that depth and other effects are applied to traditionally 2D objects. On a device, these 3D images appear to be placed at different levels above or below the device glass. 3D widgets appear to have shadows, parallax, and other traditional 3D effects.
To see examples of the Euclid 3D controls, visit the Dynamic Perspective Controls design guidelines page.
Uses of 3D in Your App
You can use the Euclid 3D Toolkit to enhance your app in two ways:
- Replace 2D controls with stock 3D controls.
- Create custom 3D controls.
The following table provides a high-level overview of each of these approaches:
|Approach||Use scenario||Implementation difficulty?|
|Replace a 2D control with its 3D counterpart.||Replace a standard 2D Android control with 3D Euclid "Z" controls.||Moderate|
|Create a new 3D control||Add a star rating control, where users can click a star to rate an item on a scale of 1-5. Note that creating a custom control involves using additional tools and usually requires help from a designer experienced with 3D graphics and animations.||Complex|
You can typically convert your app to a 3D UI by adding 3D layout classes, then converting your Android or Foundation Controls to available Euclid controls. The Euclid 3D layout classes provide 3D effects such as shadows and parallax.
Dynamic Perspective UI Terminology
This section provides an introduction to some of the terminology that you will encounter in working with Euclid classes and reading the Euclid documentation. If you are familiar with 3D graphic design, you are probably familiar with many of these terms.
A 3D asset is collection of the following items which, when combined, visually form a 3D model:
- Attachment points
Typically, graphics designers create your 3D assets using specialized tools.
An attachment point is a pre-defined point on an asset where additional assets or Euclid controls can be attached. Designers must define all attachment points when creating the asset; you cannot programmatically add or change attachment points.
The depth of a control corresponds to the depth of that control's bounding box, following the same concepts as width and height. When you place a control inside of a
ZContainer takes care of the placing the control at a certain depth relative to the screen, also called "Z value". For example, if you have a control whose depth is 6mm, that refers to the control's bounding box. If you place that control in a
ZContainer that is 2mm above the screen (Z- value), the distance from the front of the control to the screen will also be 2mm.
As the Z- value increases, control appear to be farther away from the screen. As Z- value decreases, controls appear to be closer to the screen. An object with a smaller Z value will obscure an object with a larger Z value. Negative depth means that an object appears to be in front of the screen.
For more information on depth, see Best Practices for Working with Depth, Shadows, and Dynamic Perspective Sensor Effects.
A material defines how a mapped texture and meshes are rendered in pixels on the Fire phone screen. Material properties include lighting, reflections, and visual components that are not contained within a texture.
A mesh in the context of 3D graphics is a collection of vertices, edges, and faces that define the shape of a 3D object.
Orientation and Rotation
Orientation is defined as the rotation of an object around the X, Y, and Z axes plus the magnitude of the rotation. Euclid allows you to set the rotation of an object programmatically.
The pivot point of an object is the coordinate around which it can be rotated. By default this is the center of the object. The pivot point is specified as a percentage of the size of the object, from 0.0 (0%) to 1.0 (100%). Note that this differs from the Android convention. The default coordinate system origin (0.0, 0.0, 0.0) is left, top, front. Thus, a pivot point of (0.0, 0.5, 1.0) would be at the left edge, vertically centered, at the back of the object.
|(0.0, 0.0, 0.0)||(0.0, 0.5, 1.0)|
Position is defined as the X, Y, and Z (depth) location of an object. You can specify this as an absolute position relative to the parent view or as a translation from the parent’s position, calculated during measure and layout.
Texture is a 2D pattern that can be mapped onto a 3D surface, such as a floral pattern mapped onto a round vase.
Visual Bundle (VBL)
A Visual Bundle (VBL) file is an archived collection of the assets and metadata needed to load a 3D model onto a Fire phone. The contents include glyphs, animations, attachment points, and state machines related to the animations. To learn more about creating your own custom VBLs and assets for your app, see Using the Custom Control Authoring Tools for Fire Phone.