A Dullard's Guide : sample code

Blackjack, Silverlight 1.0 Edition, Part I

Amy — Fri, 16 May 2008 23:45:00 GMT

One of my favorite HDi apps was blackjack , so I have been just itching to turn it into a Silverlight application. Now, this one wasn't quite so easy. My goal in writing blackjack for HDi originally was to take advantage of the timing element and remove...(read more)

Sliding Puzzle, Silverlight 1.0 Edition

Amy — Fri, 25 Apr 2008 23:50:00 GMT

If you're an HDi developer who spends anytime reading this blog or the MSDN forum , you've probably noticed that I've mentioned Silverlight more than a couple of times recently. Silverlight is, of course, Microsoft's platform for delivering rich interactive...(read more)

Advanced Subtitles

Amy — Thu, 22 Nov 2007 02:28:00 GMT

In HD DVD subtitling can be done via a subpicture stream or an Advanced Subtitle. An advanced subtitle is very similar in structure to an advanced application. It has a manifest, markup file, and font and is declared with its resources in the playlist. But, an advanced subtitle has some unique characteristics as well.

The markup for an advanced subtitle uses the .xas extension rather than .xmu.
The markup may not contain event, area, button, input, or option elements.
Inline styles are not permitted.
The markup may never receive focus.
An advanced subtitle may not use script files.
An advanced subtitle is rendered as part of the sub-picture plane and not the graphics plane so zOrder may not be modified
An advanced subtitle may not be active at the same time as a subpicture subtitle.

One of the great things about advanced subtitles is that they can be downloaded and run in time with the movie after the disc ships. This could significantly increase the potential audience for your movie.

Playlist Reference
An advanced subtitle in a playlist is slightly different from and advanced application in that it must include track information and many not specify zOrder.

</AdvancedSubtitleSegment>

Generating an Advanced Subtitle Markup Page
When generating subtitles, the primary information needed is the text being spoken, when it appears on screen, when it ends. The simplicity and regular structure of this data lends itself nicely to automation, of which I am a big fan.

At the end of this project you will find a sample advanced subtitles project. In this project is an Excel file with a macro that will generate an advanced subtitle markup page with the data entered on the first tab (Subtitles). The default x and y positioning and alignment may be overridden by enter a new value in the override columns. Default values for your markup page are set on the second tab (Settings).

When opening the Excel file, be sure to enable macros. There is some low level of data checking. For instance, entering a start or end value in the wrong format will turn the row red. But, always be sure to run the validator on your project to make sure the output is correct. And, once you're ready to export your markup file, press the "Export Subtitles" button at the top of the page, or press CTRL+r.

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.

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

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.