Home > Devices > Fire Phone

Dynamic Perspective UI FAQs

Introduction

This page contains answers to Frequently Asked Questions (FAQs) relating to the Euclid API for the Dynamic Perspective UI.

General Questions

Q: What is Euclid and how does it relate to the Dynamic Perspective UI?

A: Euclid is the package of APIs that allows you to include Dynamic Perspective UI controls in your app.

Q: Will my app users need special 3D glasses to view my app?

A: No, "3D" in the Amazon context refers to adding shadows, depth, and other 3D effects. App users do not need 3D glasses to view these effects.

Q: Where can I learn more about the basics of using Euclid APIs?

A: See Understanding the Dynamic Perspective UI for basic information about Euclid, including uses within your app and terminology.

Q: Do I need any special tools to add Euclid controls to my app?

A: The out-of-the-box Euclid controls should provide sufficient functionality for most apps. However, if you would like to create your own custom controls, Euclid includes tools for doing so. See Using the Custom Control Authoring Tools for more information.

Q: I have an existing app that uses standard Android controls. How difficult will it be for me to integrate Euclid controls into my app?

A: Most of your Euclid integration will be done in the layout for your activities. See the Dynamic Perspective UI Migration Guide for a basic example of how to migrate a 2D Android-based app to a 3D Euclid-based app.

Basic Controls

Q: What controls are available in Euclid, and what do they do?

A: The following table lists and describes the available Euclid controls:

Control Description
ZButton

3D button.

ZCaptionedIconButton

ZImageButton above a ZTextView.

ZCheckBox

3D check box.

ZExtrudedText 3D text view. Use this control to add 3D text to your app.
ZHeaderNavigationBar

3D header bar that can include an optional navigation button and up to two action buttons. T

ZImageButton

3D button that displays a 3D glyph.

ZMediaController

3D version of the Amazon Foundation Controls MediaController widget, which can be used to start, stop, and pause media content.

ZProgressBar

3D version of a progress bar.

ZRadioButton

3D version of a radio button.

ZRadioGroup 3D grouping widget for multiple radio buttons. Creates a multi-exclusion scope for the button group.
ZSeekBar 3D version of a seek bar, which is an interactive progress bar for users. Users can drag the slider to adjust the value of the ZSeekBar, such as a ringer volume.
ZSwitch 3D version of a switch that toggles between two preferences or settings.
ZTabBar 3D version of the multi-control TabBar widget, which provides a tabbed layout to use for navigation. Maintains selected state once a tab has been selected.
ZTabBarItem 3D tab item hosted by a ZTabBar.
ZTextView View that hosts text within a 3D layout. Text in a ZTextView is not shown in 3D; use ZExtrudedText to display 3D text. (ZTextView is simply an Android TextView that can be placed in a 3D hierarchy.)
ZToggleButton

3D version of a toggle button, which is a two-state button that can be checked as "on" or "off". The sample image shows several states of a ZToggleButton: Normal, Focused, or Selected ("On").

ZToolBar 3D version of the multi-control ToolBar widget, which provides navigation menu options for a user. Does not maintain selected state once a user makes a selection.
ZToolBarItem 3D tool bar item hosted by a ZToolBar.

Q: Where can I see examples of the available Euclid controls?

A: In the design guidelines, the Dynamic Perspective Controls page shows an example of each Euclid control.

Q: Are there Euclid versions of ListView, GridView, (e.g. ZListView and ZGridView), or picker controls available?

A: Euclid does not include these controls, but you can mix these controls into your app by using an Android layout, adding your 2D controls, and adding Euclid Z-controls wrapped in a ZContainer.

Q: How can I tell what the 3D counterparts are for my 2D controls?

A: See the Dynamic Perspective UI Migration Guide, which contains a matrix that maps 2D controls to their 3D counterparts.

Q: Which control should I use to set a preference to "true" or "false"? Do other apps use check boxes or switches for this?

A: Use a ZSwitch control to set True or False preferences.

Q: Why can't I resize the ZSwitch component?

A: Euclid does not currently support re-sizing the ZSwitch control.

Themes

Q: Help! Why am I seeing a message about using a Euclid theme when launching my app? For example, "Must use a descendant of a Euclid theme to use Euclid Controls"?

A: You might see this error if you are using an Amazon theme for your app, rather than a Euclid theme. You must use a Euclid theme with Euclid controls. Euclid themes are configured to display optimal customizations across controls.

Switch your theme to a Euclid theme, and see if that fixes the problem. See Apply Themes to Your App for more information and proper syntax.

Q: If my layout mixes Amazon 2D controls with 3D controls, do I still use a Euclid theme? Or should I not even be mixing 2D and 3D controls?

A: Yes, you can mix 2D and 3D controls. Use an Android layout and wrap your 3D controls in a ZContainer. Always use a Euclid theme when using Euclid controls to avoid compatibility errors.

Layouts

Q: I have five different controls in my layout. Do I need to wrap each control in separate ZContainers, or can I wrap them all together in one ZContainer?

A: Both approaches work, although you might want to test each approach to see which works better for your layout or app.

If you choose to wrap each control individually, make sure that you provide sufficient padding to help avoid wrapped objects from being visually clipped. Enabling Auto Padding on your ZContainer helps mitigate clipping.

Your ZContainer must also be large enough to hold any effects that happen to the control because of head tracking.

You might need to test different layout options and determine through trial-and-error what works best for your app. See Best Practices for Performance Optimization for recommendations related to performance.

Q: What is the difference between a ZLinearLayout and a LinearLayout? When should I use one versus the other?

A: ZLinearLayout is the Euclid version of a LinearLayout. When you should use one versus the other depends on whether you plan to place your layout inside or outside of a ZContainer or ZViewHost. If you are placing your layout within a ZContainer or ZViewHost, use a ZLinearLayout. You cannot use a ZLinearLayout outside of a ZContainer/ZViewHost, and you cannot use a LinearLayout inside of a ZContainer/ZViewHost. If you are placing numerous 3D controls in your activity's layout, place them inside of a ZLinearLayout that is within a ZContainer /ZViewHost.

3D Content and Effects

Q: How can I tell where I should place my controls on the Z-axis?

A: Wrap your Euclid controls in a ZContainer class for optimum placement on the Z-axis. See Best Practices for Working with Depth, Shadows, and Dynamic Perspective Sensor Effects.

Q: Do Foundation or standard Android controls support shadows?

A: Foundation and standard Android controls do not support shadows.

Q: Should all of my Euclid controls cast shadows?

A: No. You can choose what controls cast shadows. In fact, some controls should not cast shadows. Text should not cast shadows because shadows impede readability.

Q: How do I add 3D content to a control?

A: 3D content can be accessed from a Visual Bundle (VBL) file. Euclid includes several built-in VBLs that you can use to customize the look and behavior of your controls.

To specify a 3D scene from a built-in VBL for a control to display, add links to the VBL file and scene to your layout XML file as attributes of your control.

For example, the following XML specifies that a ZImageButton control will display a scene from the built-in "glyphs" VBL file called "glyph_new":

<com.amazon.euclid.widget.ZImageButton
    android:id="@+id/zbutton2"
    android:layout_width="50dp"
    android:layout_height="wrap_content"
    euclid:layout_depth="wrap_content"
    android:onClick="onClick"
    euclid:vbl="glyphs"
    euclid:scene="@euclid:string/glyph_new"/>

To specify a custom 3D scene for your control to play:

  1. Copy your VBL file into the res/raw directory of your app.
  2. Add the VBL and scene location to the XML attributes for your control.

    For example, the following XML specifies that a ZImageButton control will display "my_other_scene" from a custom "my_vbl" file:
<ZImageButton
 euclid:vbl="@raw/my_vbl"
 euclid:scene="my_other_scene.scene"
     …/>

Q: Are there any standard 3D glyphs included in the Fire Phone SDK?

A: Yes, to view a list of built-in glyphs, see Incorporating Glyphs into Your App.

Q: How can I create my own custom 3D assets and animations?

A: See Using the Custom Control Authoring Tools for Fire Phone for information on creating your own 3D assets.

Q: I don't see any instructions for creating the 3D icon for my app that appears on the Fire carousel. How do I do that?

A: You can use 3D assets within your application; however the 3D icons for display in the carousel is an experimental feature that Amazon is piloting with select developers. Amazon will be making this capability more broadly available in the future. In the meantime, if you are interested in being part of the pilot program, please contact: Firephone-3D-Carousel@amazon.com.

Object Properties

Q: What is a "Quaternion", and why did you choose a "Quaternion" to represent an object's orientation? Why not choose something more widely-used to represent rotation?

A: The orientation of an object can be represented in a three-dimensional space using three common methods:

  • Euler angles
  • Rotation matrices
  • Quaternions.

The three approaches are equivalent in that you can convert between them and write static functions like makeQuaternionFromEulerAngles(alpha, beta, gamma), but what advantage do Quaternions have over the other two options? Consider the three common actions performed with orientation:

  1. Construction from known initial values (e.g., "show me the boat rotated about 20 degrees around the Y axis and tipped a little towards me.")
  2. Combination of an existing orientation and a delta (e.g., "take the currently rotated boat and tip it another 10 degrees towards me.")
  3. Interpolation between two orientations (e.g., "smoothly rotate the boat between its current orientation and an orientation where we are facing it head on, and the boat is tipped back about 30 degrees".)

Euler angles can only do #1, Rotation matrices work well for option #1 and #2, but only Quaternions work well for all three options.

Q: Does Euclid support the Alpha property? If not, why?

A: Euclid supports the standard Android visibility property (VISIBLE | GONE), but does not have alpha support. Alpha support is difficult to implement in 3D. For example, if you have an object with an alpha value of 0.5, should the object be rendered like a tinted window where you can see the internal structure of the object as well as the objects behind it? Or should the object be rendered as if you had taken a picture of the solid object and printed a light copy of the picture on a piece of glass and held it up in the scene? The first option is straightforward in a 3D system, but computationally expensive and requires the artists develop objects with fully-realized internal structures (rather like building a car out of clear plastic). The second option requires objects in the system being rendered independently and then blended in with the scene, which makes shadow casting and occlusion non-intuitive.