Table of Contents
This page contains answers to Frequently Asked Questions (FAQs) relating to the Euclid API for the Dynamic Perspective UI.
General QuestionsQ: 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.
Q: What controls are available in Euclid, and what do they do?
A: The following table lists and describes the available Euclid controls:
ZImageButton above a ZTextView.
3D check box.
|ZExtrudedText||3D text view. Use this control to add 3D text to your app.|
3D header bar that can include an optional navigation button and up to two action buttons. T
3D button that displays a 3D glyph.
3D version of the Amazon Foundation Controls MediaController widget, which can be used to start, stop, and pause media content.
3D version of a progress bar.
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.)|
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
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
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
A: Euclid does not currently support re-sizing the
ThemesQ: 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.
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
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.
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?
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
ZViewHost. If you are placing your layout within a
ZViewHost, use a
ZLinearLayout. You cannot use a
ZLinearLayout outside of a
ZViewHost, and you cannot use a
LinearLayout inside of a
ZViewHost. If you are placing numerous 3D controls in your activity's layout, place them inside of a
ZLinearLayout that is within a
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:
- Copy your VBL file into the
res/rawdirectory of your app.
- Add the VBL and scene location to the XML attributes for your control.
For example, the following XML specifies that a
ZImageButtoncontrol 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.
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
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:
- 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.")
- Combination of an existing orientation and a delta (e.g., "take the currently rotated boat and tip it another 10 degrees towards me.")
- 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.