A Dullard's Guide : HD DVD

Xbox 360 HD DVD Emulator Request Update

Amy — Tue, 11 Mar 2008 22:19:00 GMT

Any of you who made requests for the Xbox 360 HD DVD emulator last week should have received at least an initial email with further instructions on getting access to the emulator support site on http://connect.microsoft.com/ , signing the end user licensing...(read more)

Overwhelmed

Amy — Thu, 06 Mar 2008 03:50:00 GMT

Okay, so it turns out that offering the emulator for free was WAY more popular than we had anticipated. Josh (Xbox 360 HD DVD Emulator Support Program Manager) is just a tad bit buried under all the emails right now, so please be patient with the delay...(read more)

Xbox 360 HD DVD Emulator - Now Free

Amy — Wed, 05 Mar 2008 04:57:00 GMT

UPDATE 3/18 : The Xbox 360 HD DVD Emulator is no longer available. For more information, please see: http://blogs.msdn.com/amyd/archive/2008/03/18/tokens-gone.aspx The Xbox 360 HD DVD Emulator is now available as a free download on Xbox Live Marketplace...(read more)

No Regrets

Amy — Wed, 20 Feb 2008 23:32:00 GMT

Yesterday was some day, huh? Even though rumors have been rampant for over a week now, it doesn't make it any easier to hear. Toshiba's going to discontinue the HD DVD business. It seems that's all anyone's been talking about. Engadget ran a snarky article on what you can do with your HD DVD player.

You know what I did with my HD DVD player? I went to Amazon and bought more HD DVDs for it. And then I watched Queen: Rock Montreal - which is pretty freaking awesome.

I do not regret choosing HD DVD. I bought my A2 for $250 and it came with 5 free movies by mail - though, not quite as good as the people who bought it in the last few months for $199 or less with 5 free movies immediately plus 5 more by mail. I have a modest collection of HD DVDs which I have enjoyed watching. And, it upscales my standard def library. Even now, the other format doesn't have players for $250. And, prices on those players are predicted to go up.

Right now, the two top selling DVD players- overall, not just high def - are Toshiba HD DVD players which tells me that I am probably not alone in my thinking.

To everyone who's been following along on this blog for the past ten months, thanks for reading. I hope to bring you more interesting code samples on new exciting technologies in the not too distant future.

Happy Programming :)

-Amy

Xbox 360 HD DVD Emulator Now Available

Amy — Thu, 13 Dec 2007 19:02:00 GMT

The Xbox 360 HD DVD Emulator is now available! The emulator is downloaded through Xbox LIVE Marketplace on your existing Xbox player. The Xbox 360 HD DVD Emulator can run projects from an optical disc, an external USB drive, or from a network drive, and logs API calls, errors, warnings, and exceptions with time code information to a networked PC. The emulator also comes with support provide through the Microsoft Connect site.

Required Hardware:

Retail Xbox 360 or Xbox 360 Elite (with a hard drive)
Xbox 360 HD DVD add-on
Xbox Live Account (silver or higher)
A PC running Windows XP SP2 or Vista and .NET Framework 2.0 for optional logging

Purchase and Installation:

Visit www.ThisIsHDDVD.com/emulator to purchase a redemption token.
You will receive an email with an Xbox Live redemption token to download the emulator and an invitation for the Microsoft Connect support site.
Download the PC installation files and best practices document from Microsoft Connect

Enter your Connect invitation ID at https://connect.microsoft.com/invitationentry.aspx
Download the installation file at https://connect.microsoft.com/Downloads/Downloads.aspx?SiteID=508.
The .msi contains logging software and a CHM help file - READ THE CHM - There are detailed installation and setup instructions to guide you.

Download the emulator to your Xbox

On your Xbox, sign into Xbox LIVE
Navigate to the Xbox LIVE Marketplace tab and select Redeem Code.
Enter your redemption code for the HD DVD Emulator.
After successfully redeeming the pre-paid code, select "Yes" to download.

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

Error Codes, Toshiba Edition

Amy — Tue, 27 Nov 2007 20:01:00 GMT

If you know what an error code means, it can be immensely helpful in diagnosing the problem with your project. Below are some of the more common error codes found on Toshiba Players and their potential cause. There is a similar post for Xbox HD DVD add-on error codes. Note: the contents of this post may change overtime.

Note to Consumers: This blog is targeted at content authors who create all those cool applications for HD DVD and might possibly encounter these errors during development. Of course the hope is that you never see these errors, but if you're reading this, that probably isn't the case. Should you receive an error on your HD DVD player, I would recommend the following:

Update your player firmware. The issue you are encountering may already have a fix released that you can easily download using the internet port on the back of your player. For more information, see: http://www.tacpservice.toshiba.com/ConsumerProductSupport/productupdatesandnotices.asp
Clear your persistent storage. Some discs download new content and should there be a problem with that download, the disc may not play correctly. You would only need to clear the persistent storage for that particular title (not all of your titles). For more information, see: http://www.universalhidef.com/support_errors.aspx#DeletePersistentStorage
Exchange the Disc. If a specific disc will not play, it could be a bad disc. It may have been scratched or there may be an anomaly on the disc that prevents it from being read by the player. Most retailers will allow you to exchange a bad disc for a new copy of the same title.
Contact Toshiba. When all else fails, call customer support and ask them what to do. http://www.tacp.toshiba.com/customersupport/contact.asp

Error Code

Description

Possible Causes

0x40**C00B

0x408BC00B

0x4094C00B

Resource Load Failure

Playlist is referencing a resource that does not exist or with a size attribute that is too small

0x40**C00C

0x408BC00C

0x4094C00C

Script Failure

Script is throwing an exception that is unhandled. Make sure to use try-catch blocks in your script.

Script is missing a semicolon - run the validator on your project

0x40**C00D

0x408BC00D

0x4094C00D

Unknown markup or script error

This is a sort of "catch all" error. If it happens immediately, the format of part of your script may not be valid.

If this erorr happens after your app has run for a while, this could be an indicator that the player has run out of memory. Check your code for possible memory leaks, particularly those resulting from closures and circular references.

0x40**C2**

Playlist Load issues

0x40**C201

0x408BC201

0x4094C201

AACS Error for playlist loading

0x40**C202

0x408BC202

0x4094C202

Fatal Error of AACS

0x40**C203

0x408BC203

0x4094C203

Read/Parse Error of playlist file

0x40**4203

0x408B4203

0x40944203

AACS Read/Parse Error of playlist file

AACS key does match key used to encrypt playlist

0x40**C5**

Video Playback Errors

0x40**C504

0x408BC504

0x4094C504

Video Controller Error

titleDuration of PrimaryAudioVideoClip is too long

EVOB is missing

0x40**C8**

Resource Errors

0x40**46**

Graphics Errors

0x40**C601

0x408BC601

0x4094C601

Pixel Buffer Overflow

Pixel buffer is impacted by all graphics (PNGs and JPEGs) and render font glyphs in all loaded applications must not exceed 2x1920x1080 ( 4,147,200 pixels)

0x40**C7**

Network Errors

0x40**C701

0x408BC701

0x4094C701

DiscID missing from DISCID.DAT

Run the DiscID creation tool that ships with the interactivity jumpstart kit with the following parameters (adjust GUIDs as needed):

"C:\Program Files\HD DVD Interactivity Jumpstart\Tools\CreateDISCID.exe" -c DISCID.DAT

-provider "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFF1"

-content "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFF2"

-disc "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFF3"

0x81000C03

Markup Resource Load Failure

A graphic referenced in the markup may be missing from resources.

A markup element containing text could not be released at the end of an application

0x10004050

0x200bc601

Possible internal player issue

Contact Toshiba
http://www.tacp.toshiba.com/customersupport/contact.asp

0x2007c5c2

Wrong Firmware Version

Update Player Firmware
http://tacp.toshiba.com/tacpassets-images/notices/hddvd-updateingfirmware.asp

Error Codes, Xbox Edition

Amy — Tue, 27 Nov 2007 20:00:00 GMT

If you know what an error code means, it can be immensely helpful in diagnosing the problem with your project. Below are some of the more common error codes found on the Xbox HD DVD add on and their potential cause. There is a similar post for Toshiba player error codes. Note: the contents of this post may change overtime.

Update your player firmware. Make sure your firmware is up-to-date. For more information, see: http://www.xbox.com/en-us/hardware/x/xbox360hddvdplayer/download.htm#liveupdate
Clear your persistent storage. Some discs download new content and should there be a problem with that download, the disc may not play correctly. You would only need to clear the persistent storage for that particular title (not all of your titles).

1. Launch the Xbox dashboard
2. Navigate to the System blade
3. Select Memory
4. Choose HD DVD
Read Andy's Troubleshooting Guides.
General: http://blogs.msdn.com/andypennell/archive/2007/10/25/xbox-360-hd-dvd-drive-general-troubleshooting.aspx
Movie Specific: http://blogs.msdn.com/andypennell/archive/2007/10/25/xbox-360-hd-dvd-drive-movie-specific-known-issues.aspx
Check Your Cables. The add-on drive connects to the Xbox with a USB cable. Try a different cable.
Exchange the Disc. If a specific disc will not play, it could be a bad disc. It may have been scratched or there may be an anomaly on the disc that prevents it from being read by the player. Most retailers will allow you to exchange a bad disc for a new copy of the same title.
Contact Support. When all else fails, call customer support and ask them what to do. http://www.xbox.com/en-US/support/contact/?WT.svl=nav

Error Code	Description	Possible Causes
0x86670001	XPLAYER_W_ACTION_NOT_AVAILABLE
0x86670002	XPLAYER_W_NETWORK_UNSUPPORTED
0x86670003	XPLAYER_W_SUBVIDEO_UNSUPPORTED
0xC6670001	XPLAYER_E_READ
0xC6670002	XPLAYER_E_PARENTAL
0xC6670003	XPLAYER_E_REGION
0xC6670004	XPLAYER_E_DRM_VIOLATION_STOP
0xC6670005	XPLAYER_E_INCORRECT_SYSVER
0xC6670006	XPLAYER_E_IXP_PROVIDER_FAILED
0xC6670007	XPLAYER_E_SECURE_ACCESS_FAILED
0xC6670008	XPLAYER_E_VCP_FAILED
0xC6670009	XPLAYER_E_PRIVATE_FAILURE
0xC667000A	XPLAYER_E_CANT_LOAD_RESOURCE	Playlist is referencing a resource that does not exist or with a size attribute that is too small
0xC667000B	XPLAYER_E_SCRIPT_FAILED	Script is throwing an exception that is unhandled. Make sure to use try-catch blocks in your script. Script is missing a semicolon - run the validator on your project
0xC667000C	XPLAYER_E_FILE_INCOMPLETE
THERE WAS A PROBLEM WITH LICENSING FOR THIS CONTENT		There could be a legitimate problem with the licensing on your content. Or, this could be a result of the player has run out of memory due to a memory leak. Check your code for possible memory leaks, particularly those resulting from closures and circular references with timers and HTTPClients.
CANNOT READ DISC		Bad connection: Try playing a DVD or using a different USB cable Bad disc: Try playing a different HD DVD http://support.microsoft.com/kb/927407/en-us

Additional Xbox HD DVD add-on support can be found at:

Trouble shooting tips from Andy Pennell
Specific movie issues
Cannot read disc, but no error code
How to use the Xbox HD DVD add-on
Modifyting network settings

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.

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

Making the Most of Markup

Amy — Tue, 26 Jun 2007 21:08:00 GMT

Before I started working on HDi, I was a web developer. I found the transition to HDi pretty easy because the markup and the script were already so familiar to me. There is, however, a very big difference with HDi markup that web developers should learn in order to make their applications more efficient. Unlike HTML, HDi can use timing that is a subset of SMIL to modify the UI. Those of us who come from the web world might want to shy away from this because it's unfamiliar. We know how to animate the UI via the script and we are comfortable with that. But, if you take the time to learn markup timing, you can make your applications more efficient, your animations smoother, and your script cleaner.

title clock vs. page clock vs. application clock

Timing elements can use the page, application, or title clocks. In timing elements that uses the title clock, times are relative to the timeline of the title that is playing. In timing elements that uses the application clock, times are relative to the point that the initial markup page loaded. In timing elements that use the page clock uses, times are relative to the point that the current markup page loaded. If your application has only one markup page, page and application clocks will behave the same way. When using a title clock, you can go back in time to re-trigger cues. You cannot go back in time with a page or application clock.

Because times are relative to the title timeline, timing elements that use the title clock can only be used in a title application. Also, XPath expressions cannot be used with the title clock. However, because this clock is tied to the title timeline, this timing element is very useful when doing a linear presentation that is tied to the movie that is playing such as the Warner Bros. IME or Universal's U Control. If there are elements you want to appear on screen at specific points in the movie, use the title clock. If you want to your subvideo to appear at a particular point in the movie and fade out at another point, send an event to your script using the title clock.

When using a timing element to modify style based on which element has the focus or which menu is opened, you will most likely use the application or page clock. If you want to use an XPath expression or an XPath variable to trigger a cue, it must exist in a timing element that uses a page or application clock.

And, something to note - your markup can contain multiple timing elements. So, you may have a title clock on one timing element that triggers your picture-in-picture to appear on screen and specified points in the movie. And, you may have a timing element with an application clock that manages the UI for the menu that allows the user to specify the size and position of the picture-in-picture when it does appear.

<par>

</event>

</cue>

</event>

</cue>

</par>

</timing>

<par>

</event>

</cue>

</event>

</cue>

</par>

</timing>

XPath variables

The markup is very good for modifying the style, but not so good at handling more complex logic - that's where the script comes in. Markup communicates with the script via events - that a button has been focused or actioned or a time code has passed. Script can communicate back by setting XPath variables - that the UI needs to be updated.

Markup sends event:

</event>
</cue>

Script receives event:

addEventListener("custom", handleCustom, false);

Script sets XPath variable

function handleCustom(evt) {

document.setXPathVariable("CUSTOM_VAR",evt.foo);
}

Markup uses XPath variable:

</par>

An important note about XPath variables - they are strings that you can reference in "select", "begin", or "end". They cannot be anything other than a string. They cannot be used in a "set".

Nesting pars

As we put more UI work on the markup, we inevitably will have more XPath expressions to evaluate at each tick. More XPath expressions to evaluate at each tick will slow your application, so the key is to nest your pars and seqs so that XPaths expressions that don't need to be evaluated aren't.

For instance, let's say you have a menu with sub menu A and sub menu B. Sub menu A has buttons 1, 2, and 3. Sub menu B has buttons 4, 5, and 6. You do not need to listen for focus or action on buttons 4, 5, or 6 if sub menu B is closed, and conversely, you do not need to listen for focus or action on buttons 1, 2, or 3 when sub menu A is closed.

...

</cue>

...

</par>

...

</cue>

...

</par>

Note that the cues contained within these pars will end when their parent does regardless of the cue's end trigger.

Choosing the right "end"

Cues need to have an "end" or a "dur". Cues that last too long might result in button triggers being missed because the cue was not able to restart in time. Cues that are too short might result in the trigger being missed completely should frames be dropped.

When triggering an event when a button is actioned, you can use the state of the button no longer actioned as a cue end.

</event>

</cue>

In the example above, a node was selected in begin. The same node is used for our end trigger, so we can use defaultNode() instead of selecting by id again.

Perhaps you want to use markup to set the focus on a button. The cue that does this can end as soon as that button gets focus.

</cue>

And if you've done done your nesting as shown above, maybe your cue shouldn't end until its parent has. In this case you can set your cue's end to false and it will only end when its parent does.

fill="hold"

Sometimes you don't want to set the style of an element; you want to animate it over a duration. Using "hold" for the fill attribute tells the markup to maintain the final value at the end of the animation. Note that even with fill="hold", the style will be reset when the parent par ends.

</cue>

The fill attribute is particularly useful when you animate a style. Be careful about using it on a set tag or where a parent par does not end or you may end up holding a style for longer than you intended.

Use the Schemas as Your Guide

The markup schemas can be downloaded and associated with your XML editor to assist you as you are writing your markup. With the schemas associated in Visual Studio, Intellisense will guide you through allowed tags and available attributes and the corresponding chapter in the spec as you type. More information about downloading and associating the schemas can be found in one of my previous blog posts (http://blogs.msdn.com/amyd/archive/2007/05/07/intellisense-it-s-a-good-thing.aspx)

Mixing script and markup

There will be times that you want to modify your markup styling with script. Keep in mind that when you use script to modify the style that the script now has control over that style until you call unset. In general, I try to avoid having both script and markup modify the same element. Use markup as much as you can. But, if you have a situation where you have to modify the style with markup and script, definitely read Peter Torr's blog about using unSetProperty (http://blogs.msdn.com/ptorr/archive/2006/09/08/746678.aspx)

Final Thoughts

HDi developers should keep in mind that players currently on the market may exceed the minimum performance requirements in the spec and that it's best to consider how your HDi code can be made more efficient overall and not benchmarking performance against specific players. Firmware for players may be released periodically to improve performance; however the markup engine may permit greater performance improvements than the script engine as the player knows exactly how your markup will behave at each tick. It can not predict the path your script will take at each tick. This does not mean script is bad - good script is still good, and bad markup is still bad. But, this does mean that you can create more efficient applications with smoother animations if you offset some of your application's load to well structured markup.