|
|
 |
 |
 |
|
Designing for Television
Because a television screen differs from a PC monitor, you’ll always need to preview your application’s appearance on a TiVo box to prevent surprises. For example, most analog televisions are incapable of displaying an entire 640x480 image due to the frame surrounding the picture tube. Certain well-defined subsets of the screen are called action safe and title safe. It’s fine to use full-screen images, but never put text outside the title safe area and don’t put anything important outside the action safe area.
The HME protocol includes integer constants for action and title safe areas:
SAFE_ACTION_H
SAFE_ACTION_V
SAFE_TITLE_H
SAFE_TITLE_VTVs are designed to overscan the picture; the outer 5 to 10 percent of the picture won’t be visible on the screen. Text should not appear outside the title safe area. Important picture elements should not be placed outside the action safe area (Figure 3-1).
You can use these constants to lay out your application in the appropriate areas of the screen. The HME Simulator also includes action and title safe regions that approximate those areas on the television screen.
In designing for television, be sure to use NTSC safe colors to be sure your application looks as good on a television screen as it does on the computer monitor.
Figure 3-1. Action and title safe areas on the screen
HME Simulator
The HME Simulator is an HME Receiver that roughly approximates the TiVo box. Using the Simulator makes it easy to prototype applications rapidly. The Simulator also contains some useful debugging tools.
The HME Simulator is different from the TiVo box in several crucial respects:
For these reasons, be sure to test your code regularly on the TiVo box as well as on the Simulator.
Figure 3-2 shows the HME Simulator and its File menu options:
Features
The Simulator performs the following functions:
- Displays the view hierarchy
- Shows resource use
- Highlights a resource or view when you select it; allows you to view the selected object in the view hierarchy
- Allows you to preview title/action safe areas of the screen
- Enables debug output
- Takes a snapshot of the HME application currently running
- Reconnects automatically
Figure 3-2. HME Simulator and File menu.
File Menu
The File menu has the following options (described in more detail below):
Show Views and Show Highlight
The Show Views window is useful for debugging view geometry and visibility issues. When you double-click the Simulator icon in this window, the top of the view hierarchy becomes visible. You can then open and close successive views in your application. As the following screen shows, this window displays the size of each view as well as details about the resource it contains.
When you also enable the Show Highlight feature, the Simulator highlights the selected view or resource and also highlights the same view or resource in the Show Views window. This allows you to see where the object is in the view hierarchy and to view its coordinates and associated data.
Resource Usage
The following figure shows the Resource Usage window.
The Sim column lists the number of active resources of each type currently in the Simulator. The GC column lists the total number of resources of each type that actually exist (that is, the Simulator has stopped using these resources but they have not been garbage collected yet).
Other totals are for the following:
Choose Run GC to perform garbage collection (delete all unused objects). This action prints a message to stdout.
Choose Dump button to print the current resource usage report to stdout. This option allows you to take a snapshot of resource usage at a given time.
Show Safe Action
If you select this option, two bounding boxes are displayed in the Simulator. The inner dashed-line box is the Title Safe area, and all text should be inside this box. The outer box is the Action Safe area, and all graphics in your application should be inside this box. If you follow these guides, the text and graphics in your application will be visible on all television models.
Network Menu
This menu lists the IP addresses for your computer (there may be one or more). Select the active IP address for your computer (where the Simulator is running) so that the Simulator can see the available HME applications.
Applications Menu
This menu lists the HME applications installed on your network. Select the application you want to run in the Simulator. (Alternatively, you can type the URI of the application in the Address box in the Simulator or include the URI of your application on the command line, as described in "Command Line Syntax.")
Other Features
The gray box at the bottom of the Simulator contains additional messages and warnings. When you select an object, the Simulator displays information about it in this box. The current coordinates of the cursor are shown in the bottom right-hand corner of the Simulator.
Starting an Application in the Simulator
You can start an HME application in the Simulator in one of three ways:
The Simulator will connect to that URI and begin processing the HME protocol. If the connection fails, the Simulator will automatically reconnect.
When you are running HME applications on the TiVo box, it doesn’t matter what network port an application is listening on because the application’s URI is discovered using multicast DNS. However, the Simulator is different because the URI is manually entered instead of discovered. It may be desirable to manually specify a port for the Main class using the –port command line option.
Command Line Syntax
On most platforms, you can double-click the Simulator.jar file to start the Simulator. However, if you want to use the Debug Output option, you’ll need to start the Simulator from the command line. Here is the command line syntax:
The Simulator takes the following arguments:
Key Bindings
The following table shows the mapping between keyboard keys and the TiVo remote control buttons (HME key codes). This information is also listed under the Help menu in the Simulator. Letters can be uppercase or lowercase.
Limits
The HME protocol contains specific limits for certain types of data to prevent overloading the Receiver. The application will receive a warning if one of these limits is exceeded. For example, images cannot be greater than 768kb and cannot exceed 1024x768.
It is usually possible to work around these limits by changing how the application handles problematic data. For example, images greater than 1024x768 should be scaled down before using them to create image resources.
See Chapter 4, "Rendering Constraints," and the HME SDK Release Notes for additional resource limits in the current release.
Discovery
When an HME application is started, it broadcasts its URI and title to nearby TiVo boxes. The Music, Photos, & More screen displays a list of HME applications located on the same subnet, discovered using multicast DNS (Bonjour, from Apple Computer, Inc.).
Title
In server-hosted environments, the title of the application is determined by the HME Factory. See "Application Title" for details. As described below, in the sample hosting environment, you can also explicitly define a title for your application.
Icon
The TiVo box will attempt to load an icon for the application. It will use the application’s base URI followed by “icon.png.” For example:
The easiest way to add an icon to an application is to put the icon.png file into the JAR file (or classpath) in the same directory as the application class.
Icons should be 34x26 and can use transparency (but will consume less memory if not transparent). They should use PNG format.
Important Multicast DNS Note
Due to a limitation in the Java networking code, it is possible that JmDNS will bind to the wrong interface on hosts that have multiple network interfaces. This problem can be avoided by specifying the desired network interface using the -i <intf> argument. Instantiating an application on a specific port and a specific network interface is done as follows:
java -cp hme-host-sample.jar:samples/sample.jar \ -i 10.0.0.52 -port 8888 \ com.tivo.hme.host.sample.Main \ com.tivo.hme.samples.hello.HelloWorldFind out what interfaces are available on your computer using the ipconfig command on Windows (ifconfig on Linux).
Advanced: Specifying a URI and Title for an Application
Note: In a server-hosted environment, the server creates the Factory and assigns it a URI. This URI can be obtained using the IContext.getBaseURI method. In the the sample (PC-based) hosting environment, you can specify a user-friendly URI and Title for your application, as described here. Use of this naming convention is optional.Application URI
Each application has a specific URI. Receivers connect to this URI in order to display the application on screen. Each Factory has a specific string that acts as a URI prefix for all requests. For example, if the MoviePlayer’s URI prefix is “movie” and the sample host environment is listening on port 7288, a Receiver can connect to:
This is called the application’s base URI and can be looked up at runtime using the application context (IContext.getBaseURI).
In the sample hosting environment, you can specify an application’s URI prefix by defining a special member called URI inside the application class:
The Factory class will look for the URI member when it initializes. If URI is not present, the prefix defaults to the package name. For example, the application
has the default prefix “pictures”.
Application Title
The TiVo box automatically discovers nearby applications using multicast DNS and displays a list of these applications.
In the sample hosting environment, you can specify an application’s user-visible title by defining a special member called TITLE inside the application class:
public class MoviePlayer extends Application { public final static String TITLE = "Movie Tornado!"; … }The Factory class will look for the TITLE member when it initializes. If TITLE is not present, the title defaults to the class name. For example, the application
has the default title “PictureApp”.
Finding Assets
Each factory is expected to handle HTTP requests that begin with the factory’s base URI. The host environment strips off the base URI and asks the factory for the file. By default, the factory searches for files in the following order:
- Search the classpath for the package/URI. For example, if the application is com.tivo.hme.apps.movie.MoviePlayer and the JAR file contains a file called /com/tivo/hme/apps/movie/carchase.png, it can be accessed at the following URI:
http://somemachine:1000/movie/carchase.png- Search the classpath for the URI. For example, if the JAR file contains a file called /clouds.png, it can be accessed at the following URI:
http://somemachine:1000/movie/clouds.pngThis cascading approach makes it possible to bundle multiple applications into a single JAR file. Each application should store its resources within its package. Default resources should be placed in the root directory. For example:
com/tivo/apps/movie/icon.png - the movie player’s icon com/tivo/apps/picture/icon.png - the picture viewer’s icon icon.png - the default iconWorking within the TiVo UI
Because your application is called from the TiVo user interface, you’ll want to be sure to provide a smooth transition between your application and the TiVo UI. Consider providing special handling for the Idle event, as described below, and be sure to provide a graceful exit to the TiVo Central screen when your application exits.
Teleport Keys
The TiVo button and similar keys (Live TV, Guide, and DVD) are handled directly by the TiVo box for security purposes. These special keys are called teleport keys because they send the user to a separate part of the TiVo user interface. Applications do not receive events for these keys.
Handling the Idle Event
After a certain period of inactivity (typically about 15 minutes), the TiVo UI times out to live TV. Before doing so, it sends an Idle event to your application to notify it of this impending action. Your application can handle this event if you want it to stay on the screen (and must sent an CMD_RECEIVER_ACKNOWLEDGE_IDLE acknowledgment to the Receiver within 15 seconds). Launching a screen saver at this point will prevent screen burn-in while still allowing your application to control the display.
Graceful Exit from Your Application
Applications can return to the previous TiVo screen by issuing a Resource.setActive(false) on the application while it is active. Well-behaved applications should include a way to return to this screen. Otherwise, the user will be forced to press a teleport key to exit the application.
|
|
