A Dullard's Guide : script

Exception Handling

Amy — Fri, 07 Dec 2007 22:46:00 GMT

An HD DVD player may throw exceptions during the execution of script, and if not caught will result in a player crash (showing an error code of 0x4094C00C on Toshiba or 0xC667000B on Xbox). While it's always a good idea to check conditions which could cause an exception to be thrown, an exception could still be thrown, so write your code in such a way to catch those exceptions and recover gracefully.

Your title should use try-catch exception handling in all entry points including all global code, event handlers, and function callbacks.

Detailed information about the conditions under which an exception may be thrown is detailed for each API defined in Annex Z of the DVD Specifications for High Definition Video. So, before making a call to an API, check conditions under which an exception may be thrown. For example, calling XMLParser.parse will throw an exception if XMLParser.status is not equal to XMLParser.READY, so you should check status before proceeding.

While specific exceptions can be thrown based on conditions, do not write script that relies on specific exceptions. Both exceptions and callback status values are meant to be informative. This means that they need only to signify success or failure and not specific information about what precisely caused the failure.

Keep try blocks to small chunks of code and attempt recovery wherever possible.

try

{

if (XMLParser.status() == XMLParser.READY)

{

XMLParser.parse("file:///dvddisc/ADV_OBJ/data.xml",

parseCallback);

}

else

{

//parseFailed would be a function that proceeds appropriately

//when success path can not be followed

parseFailed();

}

catch (ex)

{

//utility from "Helpful Tracing Routines" that writes diagnostic info

TraceError("EXCEPTION", ex, arguments.callee);

//parseFailed would be a function that proceeds appropriately

//when success path can not be followed

parseFailed();

}

Because using try-catch may make debugging difficult, you should use conditional compilation around calls to try-catch blocks. Conditional compilation is a proprietary Microsoft extension for Jscript that can be used during development with the Microsoft HDi simulator from the Interactivity Jumpstart Kit, the Xbox HD DVD emulator, and some software players. For more information on using conditional compilation during HDi development, read: http://blogs.msdn.com/ptorr/archive/2007/06/01/using-conditional-compilation-in-hdi.aspx

As demonstrated above, all catch blocks should also contain diagnostic trace information to further assist during development. For more information on helpful tracing routines, read: http://blogs.msdn.com/ptorr/archive/2007/06/27/helpful-tracing-routines.aspx

Virtual Keyboards

Amy — Wed, 24 Oct 2007 10:33:00 GMT

The input tag has four options for mode: password, singleline, multiline or display. When an input element with singleline, multiline, or password mode receives focus, the player may launch an onscreen keyboard to allow user input or a software player may enable use of the computer keyboard. This is not required, though (currently, only the Xbox presents the user with a keyboard). And, there's no guarantee on how a player's keyboard will look and if they will implement all the keys you want. Maybe you want an alphabetical keyboard. Maybe you want “.com” and “.net” keys to make entering email addresses easier. If you need user input, your best bet is to use the display mode on your input tag and implement your own virtual keyboard.

The project at the end of this blog has 3 sample virtual keyboards to choose from - alphabetical (for me), QWERTY, and Dvorak (for Chris). They all use the same markup, styles, timing, and script files. Only the markup files are different.

Here's a sample of what the "A" key looks like:

</div>

class
The parent div has a class attribute. A class is a way to group similar elements. It doesn't apply a style like the same attribute would in HTML. Class is used here to group which elements are hid or shown when the shift button is actioned. Class is also used to group all the keyboard keys so only one cue is needed for all buttons with the class applied.

</cue>

Custom Namespace
The buttons of the keyboard also have a "custom:key" attribute. The markup is extensible and custom attributes can be added if you add the namespace to the root element of the document.

xmlns:custom="http://custom"

This allows us to pass custom information on the button that has been actioned to the script by calling getNamedItem on the target of the action

var element = evt.target;

var attr = element.attributes.getNamedItem("custom:key");

var key = attr.value;

accessKey
Adding accessKey to a button adds a shortcut to actioning that button. This is particularly useful for the number keys because it allows users to navigate the keyboard or use the number panel on the remote. Note that for the letter keys, only keys A, B, C, and D are required to be supported. Letters E-L are optionally supported. Letters M-Z are not supported.

computeImplicitNav
As I stated earlier, shift is being handled by hiding or showing uppercase or lowercase classes. By setting style:display to none, the disabled keys are removed from display. However, changing a key's display from none to auto does not automatically add the element to the keyboard's navigation. So, when display has been updated, an event is sent to the script and computeImplicitNav re-calculates the keyboard's implicit navigation.

HD DVD Script Object Model

Amy — Wed, 24 Oct 2007 09:23:00 GMT

Have you ever been working on an HDi project and needed to look up a method name in Annex Z, but you don't have it handy (or access at all)? Well, luckily the Interactivity Jumpstart Kit ships with the HD DVD Script Object Model as a Visio file and a PNG. You'll find this very useful file in C:\Program Files\HD DVD Interactivity Jumpstart\Documentation.

And, while you're in there, check out the CHM file. It has all the command line options for the simulator and the validator, keyboard mappings, and information on how to use the CreateACA and CreateDiscID tools.

Good stuff.

Dynamic Content

Amy — Thu, 18 Oct 2007 19:01:00 GMT

Today's sample was created upon a request from my very nice and hard working office-mate Chris. Last week Chris began learning HDi. He whizzed through all the Jumpstart samples and the projects on my blog, and jumped into creating a project that would dynamically generate content on the fly. After messing around with his project for a few days, Chris said I should write a blog how to do this for other people who had questions like his. So, here it is.

There is a sample project is attached at the end of this blog. In this project, an XML file is parsed, data is extracted using XPath, text is dynamically added to the markup, and new "skins" are applied to the data by changing the loaded markup file.

XML Data
Let's say you have a project where you want to separate your data from your presentation layer. Maybe you want to download new content from the network. Maybe you want to be able to apply different skins to the same piece of content. The obvious way to separate your data is by using XML.

<?xml version="1.0" encoding="utf-8"?>

<data>

<paragraph>Lorem ipsum . . .</paragraph>

</data>

In this project, the data is in a file called data.xml and it is included with the project.

XMLParser
Before the application does anything with this XML, we need to use the XMLParser to create a DOM.

XMLParser.parse(uri, parseCallback);

function parseCallback(status, dom)

{

if (status == XMLParser.OK)

{

//do something with dom

}

XMLParser.parse takes two arguments - uri is the full path of the xml file (file:///dvddisc/ADV_OBJ/data.xml in this project) and the callback function which is called when the XMLParser has completed and is ready to return the DOM.

XMLParser also has a method called parseString which will create a DOM from a string. The parseString function returns the DOM directly without the callback.

var dom = XMLParser.parseString("<data><headline value=\"This Is The Header\"/></data>");

This can be very handy to use if your XML comes from getResponseString() from a network request or if you want to create a new empty DOM on the fly. (For more information on networking, read http://blogs.msdn.com/amyd/archive/2007/09/20/very-simple-network-example.aspx)

evaluateXPath
There are a couple of ways to can go through the newly created DOM. We could cycle through all the childNodes using DOM Level 2 ECMAScript Language Binding. Or, we can use XPath. (Note, Xpath axes are not supported). In this project, I've chosen to use some simple XPath calls to extract my data using evaluateXPath.

var nodes = dom.evaluateXPath("//headline", dom.documentElement);

evaluateXPath returns a nodeList. Since I know I'm only expecting one headline here, if I do get a non-empty nodelist, I only need the first item and its value attribute.

var headline = nodes.item(0).getAttribute("value");

The call to evaluteXPath for paragraph from my DOM will return more than one node. Also, the data here is in a text node, not an attribute. This text node is the first child of the paragraph tag and its contents can be retrieved by calling nodeValue.

for (var i = 0; i < nodes.length; i++)

{

// do something with nodes.item(i).firstChild.nodeValue;

}

I could go back to this DOM every time I need to get this data, but my application would take a performance hit. So once I get my data, I cache it for use later.

Adding Text to Markup

Okay, the XML has been parsed and data cached, so now we can put it in the markup. Here we will use the DOM Level 2 ECMAScript Language Binding to create new paragraph tags (elements that can hold text) and text nodes inside.

function addText(element, txt)

{

var p = document.createElement("p");

var text = document.createTextNode(txt);

p.appendChild(text);

element.appendChild(p);

}

And, of course once this is complete, we load the changes to the modified markup by calling document.load. For more information on why you need to call document.load, read Peter Torr's blog on Live vs. Load DOM.

Switching Between Markup Files
And, finally, just for kicks, I've added the ability to load new markup pages in order to reskin the data using the link() function.

Happy Programming!

Saving Resume Information, part II

Amy — Tue, 25 Sep 2007 01:15:00 GMT

In a previous post, I stated that when you press the stop button on your player, you have 2 seconds to continue to execute code before the player shuts down. But, that statement needs to be qualified. If you try to delay the application_end (or the deprecated stop_request) event by calling preventDefault when the user has pressed the stop, eject, or power button, the player will stop permitting preventDefault after two seconds. If you do not call preventDefault, you have a single tick to execute your code. This means that the function that handles the application_end event will be called, but not any callbacks that would have been handled in subsequent ticks. This is why using setContentInformation works, but trying to write your own XML file will not execute to completion.

However, if you just add a call to preventDefault to the event handler, and the application_end is actually triggered by the title end (and not the user pressing stop), you will end up creating an infitite loop. So, if you want to use preventDefault to allow more execution time, make sure to include an exit point in your script so that the application can end when your script is complete.

Below is an example of how the previous project would be modified if you were to call preventDefault on the application_end event:

addEventListener("application_end", handleApplicationEnd, false);
/******************************
  BEGIN ADDED CODE
********************************/
//end sequence status
var endSeq = {
  initialized:false,
  complete:false
};
/******************************
  END ADDED CODE
********************************/
function setResume( time ) 
{  
  try 
  {
    //set key for resume time
    psd.setContentInformation(contentID, resumeKey, time, setContentInfoCB);
  } 
  catch(ex)
  { 
/******************************
  BEGIN ADDED CODE
********************************/
    //set end sequence to complete
    endSeq.complete = true; 
/******************************
  END ADDED CODE
********************************/
    TraceError("EXCEPTION on setContentInformation", ex, arguments.callee);
  }
  
  function setContentInfoCB( result, key )
  { 
    if ( result == PersistentStorageManager.SUCCEEDED ) 
    {
        TraceInfo("SUCCEEDED on setContentInformation", arguments.callee);
    }
    else 
    {
        TraceInfo("FAILED on setContentInformation", arguments.callee);
    }
/******************************
  BEGIN ADDED CODE
********************************/
    //set end sequence to complete
    endSeq.complete = true;   
/******************************
  END ADDED CODE
********************************/
  }
}
function handleApplicationEnd(evt)
{
/******************************
  BEGIN ADDED CODE
********************************/
    //end sequence complete, exit
    if (endSeq.complete) return;
    
    //prevent end for another tick
    evt.preventDefault();
    //end sequence initialized, exit
    if (endSeq.initialized) return;
    
    endSeq.initialized = true;
/******************************
  END ADDED CODE
********************************/
    
    //event should pass value time based on title timeline
    //if not, use elapsedTime
    //this value could be equal to or greater than the movie runtime,
    //check for this before using value in resume
    var time = evt.time && (evt.time).match(timeCodeRegEx) ? evt.time : Player.playlist.currentTitle.elapsedTime;    
    setResume(time);    
}

Very Simple Network Example

Amy — Fri, 21 Sep 2007 02:36:00 GMT

I have received a couple requests for an example of networking, so I put something very basic together to show some simple functionality.

What it does have:

Functionality to download a file from a server to persistent storage
Calculation of percentage of download complete

What it does not have:

Server component - This will work in a development environment, but not elsewhere. You will still need to take care of AACS encapsulation and server certificates for this to function in the real world
Management of connections - You may have up to 8 active HTTP clients at one time. This script does not check for that
P-storage storage capacity check - I am assuming there is sufficient space in persistent storage to download this file. That is a bad real world assumption.
Parsing of XML from a server - Your initial server communication will most likely be to request an XML string that describes the downloads available. This XML should also contain the file size of your downloads so you can check p-storage for capacity and show download progress
Lots of other important features like using headers, using other request methods, sending files to a server, dynamically generating a timeout value, handling failed downloads when not using a timeout, etc.

//location of file to be downloaded

//the real URL should be a valid domain

var src = "http://localhost/sample_file.txt";

//destination where download will be stored

//here its the same file name as the downloaded file, stored in p-storage

var dest = "file:///required/" + PersistentStorageManager.contentId + src.substring(src.lastIndexOf("/"),src.length);

//timeout in seconds...use -1 for no timeout

var timeout = 30;

//size of download - use for percent download complete

var downloadSize = 5000;

//network object - referenced in OnDownloadStateChange

var httpClient;

//confirm user has network connection

if (Player.capabilities.network.connected == true)

{

try

{

httpClient = Network.createHTTPClient(src, Network.HTTP_GET, timeout);

httpClient.downloadFileLocation = dest;

//set a callback to track progress of download

httpClient.onStateChange = OnDownloadStateChange;

httpClient.send();

}

catch(ex)

{

TraceError("Download FAILED", ex, arguments.callee);

}

else

{

TraceInfo("Network connection not available",arguments.callee);

}

function OnDownloadStateChange(state)

{

switch (state)

{

case httpClient.STATE_RESPONSEPROGRESS:

Download is still occuring

If you know your download size, you can look at

httpClient.dataDownloaded to determine percent progress

if (downloadSize)

{

var percentComplete = Math.floor(100 * httpClient.dataDownloaded / downloadSize);

}

break;

case httpClient.STATE_COMPLETED:

Do something with file that is now at downloadLocation

TraceInfo("STATE_COMPLETED",arguments.callee);

httpClient = null; //destroy client to avoid closure issue

break;

case httpClient.STATE_ERROR:

Download failed, handle accordingly

TraceInfo("STATE_ERROR",arguments.callee);

httpClient = null; //destroy client to avoid closure issue

break;

case httpClient.STATE_ABORT:

Download aborted, handle accordingly

TraceInfo("STATE_ABORT",arguments.callee);

httpClient = null; //destroy client to avoid closure issue

break;

}

UPDATE:

Or, alternatively if you are only expecting a text string as a response from the server, don't set downloadFileLocation and on STATE_COMPLETED, use httpClient.getResponseString() to get that text string

Saving Resume Information

Amy — Mon, 20 Aug 2007 04:20:00 GMT

If you've purchased a DVD player in the last few years or used a software player, likely you've experienced a built in player feature that remembers where you last left off in the movie and allows you to resume play from that point. That functionality is player dependent - and usually the memory is discarded when you eject the disc. Because HD DVD has persistent storage, you can add this resume playback feature to your disc so that the user experience will be consistent from player to player - even if the user ejects the disc before resuming playback at another time.

To determine when the user has stopped playback on the disc, you should listen for the application_end event. Once this event fires, you have approximately 2 seconds to capture the necessary information and save it before the player shuts down. This is plenty of time to capture the elapsed time of the current title and set a key in the content's info.txt file.

The code to do this is simple and straight forward:

function handleApplicationEnd(evt)
{
    var pstoreDevices = PersistentStorageManager.getPersistentStorageDevices(PersistentStorageManager.STORAGE_REQUIRED);
    var psd = pstoreDevices[0];
    psd.setContentInformation(PersistentStorageManager.contentId, "resume", Player.playlist.currentTitle.elapsedTime, function(result, key){});
}
addEventListener("application_end", handleApplicationEnd, false);

Then, next time your discs plays, call getContentInformation on that key you just set to obtain your restart point.

In the attached project, the resume application runs as a title app. When leaving a title (either by jumping or stopping the player), the application_end event will fire and a key related to the title id will be saved with the title's resume information. On return to the title, if valid resume information is saved, the user will be asked if they wish to resume from the point they left off. If the resume time is greater than or equal to the title duration, the user will not be prompted and the title will start from the beginning.

Note that the simulator does not fire the application_end event when you shut it down. So, if you want to test this on the simulator, while the title with the application is playing, press CTRL+F to jump to the next title in the playlist which will trigger application_end.

Persistent Storage Management

Amy — Thu, 16 Aug 2007 00:16:00 GMT

One of the great features mandatory on every HD DVD player is at least 128 MB of persistent storage. Many discs on the market are taking advantage of this feature to allow you to do things like save bookmarked scenes, download new trailers, or cache your login information to access network enabled content.

The players do have a persistent storage management interface that will allow users to delete this saved content if the user so chooses. However, the player's persistent storage management menu only allows the user to delete ALL the content for a disc. So, it is HIGHLY RECOMMENDED that if you are using persistent storage for your disc, that you...

Provide your users with the ability to modify the contents saved on persistent storage for your disc from outside the player's persistent storage management menu. For instance, if your disc allows for the downloading trailers, make sure you also provide your user with the ability to delete these trailers from persistent storage via an application on the disc.
Label your content and provider folders by setting a [language]-explanation and/or [language]-icon key as specified in chapter 10 of the DVD Specification for High Definition Video. (sample code and downloadable sample application provided below). When a user does use the player's persistent storage management menu, your disc's folder will be appropriately labeled and the user can avoid confusing it with another disc and accidentally deleting it.

Launching the Persistent Storage Management Menu

To access the player's persistent storage management menu on a Toshiba player:

Press "SETUP" on the remote.
From the Setup menu, navigate to General > Maintenance > Persistent Storage
Press "SETUP" on the remote again to launch the Persistent Storage Management Menu

To access the player's persistent storage management menu on the Xbox:

Launch the Xbox dashboard
Navigate to the System blade
Select Memory
Choose HD DVD

There is a good possibility that you will see several folders labeled "Unknown Provider" and "Unknown Content". When a disc saves content to persistent storage, a unique folder is created based on that disc's content ID and nested under a folder based on its provider ID. The content and provider IDs are set in the DISCID.DAT file on the disc. If a disc sets the [language]-explanation and/or [language]-icon keys, the user will be provided with meaningful labels. If the disc does not set these keys, the specification states that the player should use "Unknown Provider" and "Unknown Content" as a label. As you can probably imagine or even see for yourself - it quickly becomes difficult to distinguish between your content and provider folders if you do not set these keys.

Creating Labels for the Content and Provider Directories

The simplest way to create a label for your content and provider directories is to set the [language]-explanation keys for these directories to a string that describes your disc title and studio. The value selected by the persistent storage management menu is determined by the user's menu language. So, if you only set the content folder's en-explanation key and the user's menu language is set to Spanish (es), the user will still see "Unknown Content". Thus, you will want to specify several languages in order to cover your anticipated audience.

To set the key for your content directory, on the PersistentStorageDevice object for your required persistent storage, you would call

setContentInformation(PersistentStorageManager.contentId, "en-explanation", "Title of My Movie", contentCallbackFunction)

where contentCallbackFunction is the callback function that handles the result from your call.

And, similarly, to set the key for your provider directory, on the PersistentStorageDevice object for your required persistent storage, you would call

setProviderInformation("en-explanation", "Title of Movie Studio", providerCallbackFunction)

where providerCallbackFunction is the callback function that handles the result from your call.

But, as I stated earlier, you will want to set this key for multiple languages. And, as you noticed, these functions have a callback and thus operate asynchronously. So, to set multiple language keys without stepping on a previous call, you will need to wait for the callback from the previous call before calling the function a second time.

The code to do this for the provider folder looks something like:

function setProviderLabel(providerInfo, languages)
{
  //get reference to required p-storage devices
  var pstoreDevices = PersistentStorageManager.getPersistentStorageDevices(PersistentStorageManager.STORAGE_REQUIRED);
  var psd = pstoreDevices[0];
  var provider_index = 0;
  function setProviderExplanation( ) 
  {
    psd.setProviderInformation( languages[ provider_index ] + "-explanation", providerInfo, setProviderExCB);
  }

  function setProviderExCB( result, key ) 
  {
    if (result == PersistentStorageManager.SUCCEEDED && provider_index < languages.length - 1) 
    {
        //interate through languages
        provider_index++;
        setProviderExplanation();
    }
  }
}
setProviderLabel("Title of Movie Studio", ["en","es","fr"]);

At the end of this post is a sample application which sets the [language]-explanation keys for both provider and content using a function called setPStorLabel which takes your content description(s), provider description(s), and array of languages as arguments. Including this script in your project will allow you to specify the labels for your provider and content folders in a single call:

setPStorLabel("Title of My Movie", "My Movie Studio", ["en","es","fr"]);

A Note About [language]-icon

10.8 in the spec states that you may also set the [language]-icon key as a way to label your content and provider directories. This requires creating a 1024x96 pixel PNG or JPEG, copying it to the content or provider directory, and setting the [language]-icon key to the location of the image. However, it should be noted that the player may only use the [language]-explanation key and not the [language]-icon key, so if you should chose to use [language]-icon, be sure to set [language]-explanation as a backup.

Blackjack

Amy — Tue, 31 Jul 2007 22:38:00 GMT

Today's game example is inspired by Ocean's 13 (available on HD DVD this fall). Blackjack is one of my favorite casino games, but I was too busy at NAB this year to make it to the tables. So, here it is for you in HDi (with some graphics assistance from John Green - Thanks, John!).

Writing the script for blackjack is pretty simple. So, the trick here is take advantage of what you can do via markup in HDi (see my last post). If you open this project up (a zip file is attached at the end of this blog) you will see that the only time the script modifies the markup is to change the value of the bet and the bank (setting state), to update the value of the hand total (again, setting state), and to set the background frame of the card container (this is the only time style is ever changed via script). Buttons focusing or disabling, divs hiding, showing, or moving is all done via markup cues triggered by XPath variables.

Suggested upgrades (read: exercise for the reader) to this app include:

Allow user to set up game

Decks in shoe
Starting bank
Minimum bet and bet increment
Username

Add a mode to accept insurance when the dealer is showing an ace
Add option to save bank at end of game to persistent storage
Add option to upload score and download high scores from network
Create a "hint" option that tells the user the recommended move

Sliding Puzzle

Amy — Sat, 02 Jun 2007 04:20:00 GMT

There have been a lot of JavaScript games created for the web. And, because HDi is based on web standards, with a little tweaking, you can easily turn many of them into games for HD DVD. And, as long as we're tweaking, we might as well add the cool additional features where we can - like screen capture.

At the end of this blog is an attachment for a sliding puzzle that takes a screen capture when the user hits the A button (F1 if you're using the simulator) and scrambles the screen. The up/down/left/right keys move the blocks into the empty space. When the puzzle is complete, the full screen image fades into view and play resumes.

Full screen:

Puzzle:

No video file is included in the attachment, so be sure to add one to your HVDVD_TS folder to take advantage of the screen capture.

For more games in HDi, check out Peter's Space Invaders and Liar's Dice if you haven't already.