HD DVD / Randomness... : iHD

What Now?

ptorr — Wed, 20 Feb 2008 22:18:46 GMT

I have had some readers ask what is to become of this blog. Well, it started out discussing Office Development, then it covered Threat Modelling, and most recently it has been about HDi. There have been several posts about the Pet Shop Boys and then there was this little post, too. That's the cool thing about Microsoft; you work on one thing for a while, and if it doesn't work out (or if you decide you want to try something new) then you just go do it.

One thing's for sure – I'm not about to start posting about BD-J authoring :-)

I still have a few script-based posts to finish, but after that I don't know how often I will update the blog because most likely I will be working on the Next Big Thing, and most likely that won't be public (and thus not blog-able). Anyway, thanks for reading and if you choose to stick around then maybe I'll post something cool again in a few months...

http://www.hddvdforever.com/

Peter.

Fun Friends for Functions, Part 2: Handling Exceptions

ptorr — Sat, 02 Feb 2008 04:24:40 GMT

Previously we looked at how you can bind a function to a set of arguments and then call the resultant function at some time in the future. This technique is very powerful, but as-is it is a ticking bomb. As Amy points out in her blog post on exception handling, you always need to be prepared to handle an exception in your code. Failure to catch an exception usually leads to playback stopping and an error diagnostic from your player.

The trouble is that when you start using bound functions, you don't always have an easy way to deal with exceptions. Typically, a bound function is used as part of an asynchronous callback, and in those cases you don't have any functions further up the stack to save you from unhandled errors. Simple, you might think, I'll just wrap the contents of my function in a try-catch and be done with it.

Not so fast.

Let's look at the example function we were using in the previous blog post:

// function to set a backgroundImage
function SetBackgroundImage(markupId, url)
{
document[markupId].style.backgroundImage = url;
}

This could throw for several reasons – for example, an element with the markupId doesn't exist, or url isn't a correctly-formatted property value. Simply wrapping this up in a try-catch would result in something like this:

// function to set a backgroundImage
function SetBackgroundImage(markupId, url)
{
  try
  {
    document[markupId].style.backgroundImage = url;
  }
  catch(ex)
  {
    // What do we do here?!?
  }
}

But there's a problem – what do we do when we catch the exception? I don't know. And that's a key thing about exception handling:

Functions should only handle exceptions if they are actually prepared to deal with them. If a function doesn't know what to do in an error condition, it should let its caller figure it out. The exception [groan] to this rule is that your top-level code should always swallow exceptions (unless of course things are so out of whack that you think the player should stop immediately).

In this case, the SetBackgroundImage function has no idea what a failure means. It might be perfectly OK if the background image can't be set correctly, or it could be totally disastrous. It all depends on the context, so the SetBackgroundImage function should remain silent on the topic of exceptions and let the calling function figure out what (if anything) to do with them.

In our particular case, let's say that the exception is benign; we are simply updating some eye-candy graphics and it doesn't matter if they fail to appear. So then: maybe we should write a wrapper function, SafeSetBackgroundImage, that does this for us?

// function to set a backgroundImage, ignoring exceptions
function SafeSetBackgroundImage(markupId, url)
{
  try
  {
    SetBackgroundImage(markupId, url);
  }
  catch(ex) { }
}

I actually like to use this approach if I am going to be calling the 'Safe' version in a lot of different places, but if it is only in one or two places that seems like too much overhead to someone lazy like me. Anytime you update the parameter list of the wrapped function, you have to update the wrappers, too. It can also hide the intent of your code by sprinkling endless wrapper functions all over the place, and this also has the productivity-reducing effect of polluting IntelliSense with unnecessary function names. Instead, we can use the same kind of nested-function trick we used in the argument-binding case to get a "safe" version of any function:

// return a version of a function that is wrapped in try-catch
// you can optionally provide an errorFunc, which will be
// called with the 'tag' parameter in case of an exception
function Function_WrapInTryCatch(errorFunc, tag)
{
// stash the target function
var func = this;

// return the nested function
return wrappedFunction;

Function.prototype.WrapInTryCatch = Function_WrapInTryCatch;

In this example, we also allow the caller of the WrapInTryCatch function to provide an optional error-handling function that will be called if an error occurs. This allows you to do things like channel all your async exceptions to the same error handling function, which can figure out what to do based on the value of the tag parameter. Now we can re-write the last couple of lines of the example as:

// Call the download function, passing in the set-image function as the callback handler
var setBackgroundHandler = SetBackgroundImage.BindToArguments("button1", "file:///filecache/bar.png");
var wrappedHandler = setBackgroundHandler.WrapInTryCatch();
DownloadFile("http://foo/bar.png", "file:///filecache/bar.png", wrappedHandler);

This helper has the same limitations as the BindToArguments function (specifically: you can't pass any arguments to the returned function, and any tracing information is lost if 'errorFunc' is called) but this is also a solvable problem.

Fun Friends For Functions

ptorr — Wed, 30 Jan 2008 03:45:34 GMT

And now for a more techy post. In ECMAScript, functions are considered first-class objects. "What," you might ask, "differentiates a 'first-class' object from a merely 'economy-class' object?" Well, the main thing is that functions in ECMAScript are treated just like any other type of data (strings, numbers, arrays, etc.) in that they can be assigned to variables, they can be passed as function arguments, and they can have properties and methods of their own. They also have a prototype object, just like all other ECMAScript objects. The upshot of this is that you can do fun things with functions in ECMAScript that you can't do in other languages such as C or Java.

In this entry I will introduce four types of "helper" functions that are ideally suited to HDi development. They are:

Binding a function to a set of arguments and / or a 'this' object
Wrapping an existing function in an exception handler
Chaining function calls together one after the other
Calling a function after a specified period of time

In all cases, you write the actual function (the one that does the interesting work) just as you normally would, but when it comes time to call that function you do something funky with it to make some magic happen. Exactly why you might want to do this will become clearer soon, but it mostly comes down to how you write event handlers and callbacks.

A common theme in this post will be that you want to avoid closures as much as possible, and using these helpers should get you a long way to doing that (even though these helper functions rely on closures, they do so in a "safe" manner). And although there are various ad-hoc ways to accomplish the same tasks, generally these require writing specialised wrapper functions or following ugly coding practices (which I might blog about in the future) when what I would prefer to focus on is writing highly readable, highly re-usable code and utilising some clever, general-purpose helper functions to take care of all the tricky dirty work.

Binding to arguments

Many operations in HDi use a callback function to notify you when a specific task is completed (such as a File I/O operation or an event handler). Oftentimes you will want to associate more information with your callback than the HDi API actually allows for, and there are a couple of ways to accomplish this. But first, an example:

Say you have an application where you want to dynamically download some images from the network and display them inside a markup page. The basic code you want to write is probably like this (the code is simplified for clarity; obviously there is some additional code to convert the onStateChange callback into a single "the download is complete" call, etc.):

// function to download an image
function DownloadImage(src, dest)
{
  var httpClient = Network.createHttpClient(src, dest);
  httpClient.onStateChange = SetBackgroundImage;
  httpClient.send();
}

// function to set a backgroundImage
function SetBackgroundImage(markupId, url)
{
document[markupId].style.backgroundImage = url;
}

// call the download function... but what next?
DownloadImage("http://foo/bar.png", "file:///filecache/bar.png");

Note that both functions have been written to be "highly readable, highly re-usable" and do one thing in a very straight-forward manner. The problem, of course, is that this code won't work because there is no way for the callback to SetBackgroundImage to communicate what markupId or the final download url is supposed to be.

One common way of solving this problem is to use a nested function, like this:

// function to download an image and set it as the background URL
function DownloadBackgroundImage(src, dest, markupId)
{
  var httpClient = Network.createHttpClient(src, dest);
  httpClient.onStateChange = SetBackgroundImage;
  httpClient.send();

  // nested function to set a backgroundImage
  function SetBackgroundImage()
  {
    document[markupId].style.backgroundImage = dest;

    // Clean up the memory
    httpClient = null;
  }
}

// call the download function and update the element 'button1'
DownloadBackgroundImage("http://foo/bar.png", "file:///filecache/bar.png", "button1");

Note that even though we've done work to ensure the closure won't memory leak memory, there is still at big problem in that neither the download function nor the background setting function are generic any more. If you want to (eg) download an XML file, or if you want to set the backgroundImage to a file on persistent storage, you will need to either add some more hacks to this function (making it less readable and less maintainable) or you will need to duplicate the code into a similar-but-not-entirely-the-same function.

The solution I prefer is to use the fact that functions are first-class objects and solve this problem using "argument binding." In this case, the code would be re-written as follows:

// function to download a file and then call 'handler' when it is done
function DownloadFile(src, dest, handler)
{
  var httpClient = Network.createHttpClient(src, dest);
  httpClient.onStateChange = handler;
  httpClient.send();
}

// function to set a backgroundImage
function SetBackgroundImage(markupId, url)
{
document[markupId].style.backgroundImage = url;
}

// Call the download function, passing in the set-image function as the callback handler
var setBackgroundHandler = SetBackgroundImage.BindToArguments("button1", "file:///filecache/bar.png");
DownloadFile("http://foo/bar.png", "file:///filecache/bar.png", setBackgroundHandler);

Now both the download function and the set-image function are still written in a clear, simple, re-usable fashion, but we can easily chain them together to get the desired result. Even the call that makes this possible (the BindToArguments call) is straight-forward and understandable. All that is missing is the magic BindToArguments helper function... which looks like this:

// helper function to return a copy of the target function, but
// bound to the original arguments
function Function_BindToArguments()
{
  // store a reference to the target function and its arguments
  var storedFunction = this;
  var storedArguments = arguments;

// return the nested function
return boundFunction;

  // nested function simply invokes the stashed values
  function boundFunction()
  {
    storedFunction.apply(null, storedArguments);
  }
}

// make the helper available to all functions
Function.prototype.BindToArguments = Function_BindToArguments;

As noted in the comments, this helper function simply stores a reference to the "target" function and the arguments that are passed to the BindToArguments call. Then it returns a nested function, which when called will invoke the stored function (SetBackgroundImage) with the stored arguments ("button1" and "file:///filecache/bar.png"). Note that the apply function is a built-in function of ECMAScript Function objects that invokes a given function with the specified 'this' object and arguments array.

This is the most basic form of a "binding" helper, and the resultant function is one that has no 'this' object and that cannot take any arguments of its own. It also can't participate in a typical logging infrastructure because much of the required metadata (original function name, number of expected arguments, etc.) is missing. The good news is that all this can be added with the help of more code, and hopefully that's something I'll be posting soon.

As usual, this is longer (and took longer) to write, so I'll have to save the other "friends" for later. The depressing thing is that actually writing the code is the easy part (and it's all done already); it's wrapping it all up in a post and explaining how things work that take forever!

HD DVD Emulator for Xbox 360!

ptorr — Fri, 14 Dec 2007 04:22:15 GMT

It's finally here! The Xbox 360 HD DVD Emulator went live today, enabling content authors to test their HD DVD content in a real-world consumer player before committing it to a shiny disc. This can save a lot of time and a lot of money for those folks building advanced HD DVD titles. It might help you save your hair, too :-)

"But," you might be saying, "doesn't Microsoft already ship an HD DVD Simulator for free? Why would I want this emulator?"

Good question. Here are just a few reasons why:

The simulator only plays Windows Media files, and poorly at that. The emulator plays real multiplexed EVOB files (with VC-1 and AVC and TrueHD etc.) that you will ship on the real disc.
The simulator doesn't support subtitles or multiple audio tracks. The emulator does, enabling you to actually test them.
The simulator shows you how your code performs on your desktop PC. The emulator shows you how it performs on real shipping hardware.
The simulator has some primitive logging functionality, but you need to do some work yourself. The emulator has very robust logging for all aspects of HDi playback (including markup timing!).

There are obviously more reasons to use the emulator, but that's a quick rundown of some of the key reasons why you might want to do it. Of course the simulator is still great for doing early title development – where access to real video and multiple audio tracks might not matter – because using the PC enables a great edit-run-debug workflow. But the emulator is absolutely critical for putting everything together, fine-tuning your code, verifying performance and compatibility, and running a through a thorough test pass prior to check-disc replication.

Simple ACA dumper

ptorr — Fri, 06 Jul 2007 00:36:00 GMT

Quick one today – if you have an ACA with some files in it, you can use the createaca tool (provided as part of the Jumpstart Kit) to list the files inside it. Trouble is that the output is not very helpful; it contains too much information.

So here is a simple JScript file you can run on the output of createaca -r to just dump the filenames (and it checks for duplicates, too!). Just copy to dumpaca.js (or the file of your choice) and run it from a command prompt. It expects a file named filelist.txt to exist in the same folder. Modifications to do whatever you want to do should be trivial...

// Open file named "filelist.txt"
‎var fso = new ActiveXObject("Scripting.FileSystemObject");
var stream = fso.OpenTextFile("filelist.txt");
var contents = stream.ReadAll();

// Regular expression to search for DATA_FNAME followed by a name
var re =/DATA_FNAME : ((?:\w|\.)+)/g;

// Lists of result data
var names = {};
var nameList = [];
var result;
var dupes = [];

// Search for every instance of the regular expression
while(null != (result = re.exec(contents)))
{
var name = result[1];

  // Record dupes
  if (names[name] != null)
  {
    dupes.push(name);
  }
  // else record new values
  else
  {
    names[name] = nameList.length;
    nameList.push(name);
  }
}

// Print results
print("---------- Complete file list ----------");

for (var i in nameList)
print(nameList[i]);

// Print dupes
if (dupes.length > 0)
{
print("---------- Duplicate file names ----------");

for (var j in dupes)
print(dupes[j]);
}

// Helper
function print(s) { WScript.Echo(String(s)); }

Helpful Tracing Routines

ptorr — Wed, 27 Jun 2007 11:37:00 GMT

Last time we looked at conditional compilation, and how using it with HDiSim could aid with interactive debugging of runtime exceptions. But as useful as interactive debugging is, there are three major cases where it is impractical or impossible:

When the bug is timing related, and using a debugger masks the bug; or
Reproducing the bug requires running a large amount of code it's impractical or laborious to step through by hand; or
You're trying to track down an issue on a real player (which you can't debug on).

In these cases, it is very useful to have some robust tracing primitives built in to your code to give you a trace (or log) of everything that the player is doing up until the time the bug occurs. I already posted a while back on red box debugging, and how that relates to printf debugging; now we're going to add some more printf-like tracing to our HDi toolkit to help diagnose issues on retail players or to trace errors through the system in critical timing sections.

The general approach is to pepper our code with calls to a trace() function that will either write the trace info to a log file, or display it on the screen, or both. Usually the trace function will be called when execution enters a new function, when an exception is handled, and at any other point in time where it is useful to know the result of a test or the value of a particular variable or property. Now, the key to any good trace log is the ability to identify the function that was active at the time a given log entry was made. Whilst it is possible to hard-code the name of the function into the trace call (for example, trace("Inside function 'foo'")), this is problematic because any time you re-name a function (or copy-and-paste it to a new function) you need to update the function name in the script. It would be much better if you could somehow automatically get the function name...

Enter the GetFunctionName function, defined like this:

// Returns the name of a function
function GetFunctionName(func)
{
try
{
var re = /function\s+(\w+)/;
var s = re.exec(func.toString())[1];

    // Based on naming convention of 'object_FunctionName'
    if (s.indexOf("_") >= 0)
      return s.substring(s.indexOf("_"));

return s;
}
catch(ex) { ; }

return "AnonymousOrUnknownFunction";
}

Given a Function object as its only argument, this function will return the name of the function (or the string "AnonymousOrUnknownFunction" if the function name is not available – for example, you pass in a function expression or a native method). It does this by creating a Regular Expression re that looks for the word "function" followed by some whitespace \s+ and then a word (\w+). If the word is found, it is "captured" (because it is in parentheses) and returned by the expression re.exec(...)[1]. The toString call inside of exec simply converts the Function object into an implementation-defined representation of the function body, but ECMA 262 defines that at a minimum this contains the function name (ie, it is a FunctionDeclaration).

OK, that's kind of useful, but how do you get the right Function object to pass to the GetFunctionName function? Good question. The answer is that you use the arguments object, and in particular the callee property; it holds a reference to the function being called. Neato, eh?

I want to take a quick detour here to say that I personally think that relying on the arguments object as a way of passing parameters to a function is a bad programming practice and should be avoided for normal development; I won't bore you with all the details, but basically it makes your code harder to read (and thus harder to understand) if all the expected parameters aren't immediately obvious from the function's declaration. Nevertheless, the arguments object is great for tracing, and so we shall use it for this.

So while we're on the subject of the arguments object, it's also worth noting that it's a great way to trace the arguments passed to a function in a generic way (again, avoiding the copy-and-paste problem, or having to keep up with added or removed parameters). To do this, we'll write another function (and a little helper) that can be used to generate a string holding the value of all the arguments passed to a function. It looks like this:

// Returns a string representing the arguments list of a function
function GetArgumentsString(args)
{
var s = "(";
var first = true;

for (var i = 0; i < args.length; i++)
{
if (first != true)
s += ", ";

first = false;

var arg = args[i];
s += ObjectToString(arg);
}

s += ")";
return s;
}

// Returns a string representation of an object;
function ObjectToString(obj)
{
try
{
if (typeof(obj) == "function")
return "function " + GetFunctionName(obj);

if (typeof(obj) == "string")
return "\"" + obj + "\"";

return String(obj);
}
catch(ex)
{
return "[native Object]";
}
}

Together these two functions will take an arguments object and return a string that contains all their values, including special handling for functions and native (host) objects. Now we can build a simple function that is used to trace function entry like this:

// Global to define whether to do tracing or not;
// Tracing can be expensive so you might not want to do it on a released title
var _DO_TRACE = true;

// Trace function name and argument list
function TraceFunctionEntry(args)
{
// Bail immediately if tracing is not desired
if (_DO_TRACE != true)
return;

var name = GetFunctionName(args.callee);
var argString = GetArgumentsString(args);
TraceString(name + argString);
}

And we can use the TraceFunctionEntry function like this:

function MyFunction(a, b, c)
{
TraceFunctionEntry(arguments);

// Do some actual work...
}

Now we just need to define the TraceString function; but that's the easy part ;-)

// Global startup code to open the diagnostics file, if necessary.
if (_DO_TRACE)
{
try
{
Diagnostics.listeners.add("file");
Diagnostics.trace.autoFlush = true;
} catch (ex) { }
}

// Function to trace a message to the diagnostics log and, if available,
// an on-screen input.
function TraceString(msg)
{
if (_DO_TRACE != true)
return;

// Write out the message to the diagnostics log
try
{
Diagnostics.trace.writeLine(msg, "Trace", 1);
} catch (ex) { }

// Try to add the message to an <input> named 'trace', if one exists
try
{
    var node = document.trace;
    if (node != null && node.nodeName == "input")
      node.state.value = node.state.value + " | " + msg;

} catch (ex) { }
}

And there you have it! I have attached a sample project that includes a couple of other helpful tracing aids (one for errors, one for informational tracing). As usual, you need to copy a file named font.ttf into the ADV_OBJ folder in order for it to work (I use the "Kooteny" sample font from the HDiSim download).

Using Conditional Compilation in HDi

ptorr — Sat, 02 Jun 2007 05:40:00 GMT

One of the cardinal rules for developing HD DVD applications is, "let no exception go unhandled." The reason for this is simple – if you fail to handle an exception, the player will kill your application and stop the disc. This leads many developers to wrap entire functions in try / catch blocks, which solves the problem but introduces some of its own.

To me, one of the biggest problems with using try / catch during development is that it makes debugging script with Visual Studio virtually impossible. For a start, you can't rely on "just-in-time" (JIT) debugging to work because you never have any unhandled exceptions. Additionally, even if you manually attach the debugger and step through your code line by line, as soon as there is an exception it will dump you out at the catch handler, losing all the context information you might need to fix the bug (stack trace, local variables, even the location in the source file).

As an example, try this script (run it under WSH with the command-line cscript //x test.js) and step through each line by hitting F11. Step over the PretendThisIsAPlatformAPI function by hitting F10 instead.

// Hit F11 to step INTO each line
try
{
foo(1)
}
catch(ex)
{
WScript.Echo(ex)
}

function foo(x)
{
// Imagine lots of complex code here...
var y = x - 1
bar(y)
}

function bar(x)
{
// More complex code here...
var y = x / 2
// Hit F10 to step OVER this function
PretendThisIsAPlatformAPI(y)
}

function PretendThisIsAPlatformAPI(x)
{
if (x <= 0)
throw("bad parameter value")
}

Note that everything is fine until you call that fake platform API. Then you are dumped back into the catch block of the global code with a message saying "bad parameter value." But what was the parameter value I passed to the function? I can't find out, because all the context (the stack frames for bar and foo) has been removed.

Is the solution to remove the try / catch block during development, then add it back at the last minute before shipping?

NO!

That is a recipe for disaster for at least two reasons:

You might forget to put it back in
You will never have tested your exception-handling code

There's a better approach, and it relies on a feature of Microsoft's JScript implementation that lets you "hide" parts of the script from JScript whilst making it clearly visible to normal ECMAScript engines. This allows you to toggle exception handling on or off during development (with HDiSim), whilst never risking having it turned off when you ship.

This feature is called conditional compilation, and here's how we use it:

The first thing to do is to activate conditional compilation. We do that like this – note how it is in an ECMAScript comment, so that other script engines will ignore the command:

//@cc_on

Next, we define a conditional-compilation variable that will determine whether or not we want exception handling (note: you can name the variable anything you want; this isn't some magic value):

//@set @enable_exceptions = true

Perhaps obviously, we set this to true if we want to handle exceptions with try / catch, and false if we do not.

Finally, we wrap our try and catch blocks with a conditional statement:

//@if(@enable_exceptions)
try
{
//@end

foo(1)

//@if(@enable_exceptions)
}
catch(ex)
{
WScript.Echo(ex)
}
//@end

Now, depending on the value of @enable_exceptions, JScript either sees this source code (when true):

try
{
foo(1)
}
catch(ex)
{
WScript.Echo(ex)
}

Or this source code (when false):

foo(1)

Non-JScript engines will always see the former source code, because they simply treat the @if statements as comments. That means they will always have try / catch turned on, and is why I say it is impossible to "forget" to turn exception handling back on when you ship.

During normal testing and development, you should leave @enable_exceptions set to true, because you need to test your exception-handling code. But when you are trying to debug a problem caused by a thrown exception, you can set it to false and use the JIT feature of Visual Studio to jump right to the line that is throwing the exception. You should then turn it back to true again after you've finished debugging, because it is possible that some players on Windows might use the JScript engine. Even then, this approach is better than manually adding and removing the exception-handling code from your applications since there's only one place in your code to do it, rather than every single location where you use try / catch.

You can try this out now, by running the sample script again with exception handling turned on and off. In this case, instead of stepping through the file with F11, just hit F5 to run the program. When exception handling is turned on, you don't get any help from the VS debugger. When it's turned off, VS will break at the offending line so you can investigate the problem and determine the right fix.

Marvellous!

Typically I have a single file, cc.js, that I always include as the first <Script> element in my manifest. It contains the @cc_on statement and the @enable_exceptions variable, along with any others I might decide to use. As part of your shipping process, you could decide to always remove this file (or replace it with one that forces @enable_exceptions to true) "just in case"...

link

ptorr — Sat, 02 Jun 2007 04:07:12 GMT

No, not the application.link API. A web link. Or two.

Some of you may have noticed a new name on the HD DVD Forums of late: Amy Dullard. She also has a great blog that focuses on getting people up-and-running with HDi. Check it out at http://blogs.msdn.com/amyd.

Another person you might recognise from the Forums, Andy Pennell, also has a blog at http://blogs.msdn.com/andypennell/.

And finally, the Microsoft "industry" site for HD DVD is http://www.thisishddvd.com. There's not much there now, but it should get better.

OK, so three links. Four if you count the forums. But who didn't know that already?

A Game of Chance that Pirates like to Play

ptorr — Thu, 17 May 2007 01:52:00 GMT

Ahoy there me laddies! Yarrrr you better be readin' this blog then matey, or you'll be feelin' the lick o' the cat come nightfall!

No, it's not Talk Like a Pirate Day; it's Let's Post Another HDi Game Day. The other week I posted an HDi sample based of the old arcade game Space Invaders. Today it's a (somewhat prettier) example that implements the old game Liar's Dice. Some of you may wonder how I chose these two games to demo as HDi applications; the rest of you already know this is to show just how easy it is to get great interactivity on a next-generation high-definition optical disc without expensive replication, without expensive programmers, and without an expensive games console to play it on. This was all written by little old me in a couple of hours, is about 130k in size (most of which are PNGs), and will play on any sub-$300 HD DVD player without first running through a performance test application. [Ed: I am currently travelling without access to a real player so have been unable to test it properly; it works on HDiSim and if there are any issues with up-to-date players I will resolve them next week]

Here's a screenshot of the game:

As with the last game, this was thrown together very quickly and doesn't necessarily represent "best practices" (I know, I know, I should be demonstrating those too). Nevertheless the concepts should be pretty easy to understand. If not, post a comment! :-)

The download is here. Enjoy.

Coloured Blocks Advancing on a Moving Block

ptorr — Tue, 03 Apr 2007 00:14:34 GMT

This blog would be titled Space Invaders, but I don't own that trademark so I had to choose something a bit more generic. This is a preliminary post to show a very hacked up version of the popular game in HDi. Note that I hope to follow up with a more complete version at some stage, but people have been asking for this so I am going to post it anyway.

Disclaimer: I hacked this together in a couple of hours after someone asked me if it could be done. It is not very good code, it uses magic numbers, it hasn't been well tested, etc. and is not functionally complete. Nevertheless, you can have some fun with it and maybe use it to build something cooler.

I also won't provide much commentary here, since I hope to do that with a better-written version soon(ish). Having said that, a very quick summary is:

You (the blue box at the bottom) move by hitting left or right on the keyboard / remote. Once moving, you can't stop until you hit the edge or turn around. You fire by hitting enter (or OK on the remote), and you can only have one bullet in the air at any given time (so don't miss :-) ).

You get 100 points for hitting an enemy. Hit them all, and you win (the "you've won!" sequence is so mind-blowingly cool that you have to see it for yourself). If an enemy hits you with a bullet, or if the bottom row of enemies advances into your "home base", you lose. Again, the cinematic for losing is simply breathtaking.

Things you might want to work on:

Add animated graphics for you and the enemies. Simple backgroundFrame animation can do this
Improve the hit-testing logic (right now, bullets are assumed to be 1-pixel wide)
Add the "shields" to the game; I planned for it but haven't done it yet
Make enemies score different points when you hit them (based on rank and how far down they are)
Have different "skill levels" if you complete one screen
Improve the code to be more modular, not query the markup page so much, and not rely on hard-coded numbers (like "485" on line 109!)
Improve perf by not doing any per-tick operations if you know nothing needs to be done

Etc.

Anywho, that's it. I'll try to do more later...

[Download the ADV_OBJ as a ZIP file]

The Difference Between “Selected” and “Current” tracks

ptorr — Tue, 20 Feb 2007 21:24:25 GMT

In HD DVD, there are two ways to figure out which subtitle or audio track the user has chosen. The selectedAudioTrackNumber (and selectedAudioLanguageCode / selectedAudioLanguageCodeExtension) properties refer to the track (language) that the user has selected, but they may or may not represent the currently-playing track / language. The currentAudioTrackNumber (etc.) refer to the track that is actually playing right now. The same goes for subtitle tracks.

The different sets of properties are basically used to ensure the user gets the language they prefer if it is available, but if not then the script code can always check what the fallback value was to display the appropriate UI. For example, assume you have a main feature with the following audio tracks:

English
Spanish
German
Japanese

And also assume you have a documentary with the following audio tracks:

English
Japanese

If the user is listening in English, it is easy. The selected and current tracks are always 1, and the language code is EN (I won't go into extensions here). Now if the user is listening to the feature in Japanese, both the selected and current tracks are 4, and the language code is JA. Now the user jumps to the documentary, but track 4 no longer exists. Using the selection algorithm (section 4.3.19.4.2 of the spec) the system searches for another Japanese track and finds it in track number 2. So the selected track is still 4 (so that when jumping back to the main feature, the right track is selected) but the current track is 2. Both selected and current language is still JA.

Now if the user is listening to the feature in German (track 3), we have a bit of a problem. Switching to the documentary, there is neither a track number 3 nor a DE-language track, so we select the lowest available instead (English). Now the selected track / language is 3 / DE, but the current track / language is 1 / EN. But when they switch back to the feature, they get their native German back again.

A tip for writing script for HD DVD

ptorr — Fri, 16 Feb 2007 22:46:23 GMT

A very quick tip today, although this one trips me up a lot.

When you write script files for your HDi applications, always include a blank line at the start of the file and at the end of the file.

This is because the player will concatenate all the individual files together and execute them as a single large virtual file. So, for example, if you have two files like this:

first.js

var x = 42;
// end of first.js

second.js

var y = 42;

Then the player will see this:

<virtual_file>

var x = 42;
// end of first.jsvar y = 42;

And then later on when you try to reference the y variable, it doesn't exist because it was considered part of the comment. Doh!

At least, that's what the players do, but HDiSim doesn't. Which is why you can get away without the padding when running on the simulator, and then you get weird errors when running on the emulator / player.

Red Box Debugging

ptorr — Thu, 01 Feb 2007 23:07:01 GMT

Today I have a simple debugging tip.

Sometimes when you have an obscure bug, you need to answer the question "is my code even getting executed?" Often you can find that really obscure bugs are caused simply by a bad conditional, a typo, an unexpected exception, or some other flow-control issue that bypasses your code altogether.

Whilst you can use an interactive debugger such as Microsoft Visual Studio for tracking down some of these things, debuggers aren't always available (eg, if you are on a hardware emulator), and if the bug is timing-related then they hamper your ability to reproduce the problem. Worse still, if your bug is in a declarative timing section (rather than in a script file) there's currently no way to debug that at all.

So you need something a bit less impactful.

In the good old days of C programming, people used to use "printf debugging" to display a message on the console indicating that a particular line of code had executed, and possibly to show the value of a variable. In the web world, this was changed to "alert debugging" where a popup window was used to the same effect.

For HD DVD, I like to use "red box debugging". Basically I create a big red div in my markup file and set style:display="none". Then at the point in my script where I want to "prove" that it gets executed or not, I simply say document.whateverTheIdIs.style.display = "auto" and see if the red box appears. And if your bug is timing related, you simply has a cue that does a <set style:display="auto" /> and similarly proves (or disproves...) that your program is working as planned.

That's all J

Simple Pre-Processor for HDi

ptorr — Wed, 10 Jan 2007 11:07:00 GMT

Hope you all had a good break. I haven't blogged for a while due to travel (both business and pleasure) and laziness… but I thought I'd start off today with simple pre-processor for HDi.

One of the things that is missing from HD DVD is a good pre-processor; anyone familiar with C will know of all the good (and evil) things you can do with a few #define macros. Anyone not familiar with C, well, you don't know what you're missing out on :-)

Anyway, what I am basically talking about is the ability to define macros (symbolic constants; shortcuts; expansions; whatever) that you can use in your markup files and script files to simplify development.

Here's a common problem scenario (at least for me):

Lay out some simple markup
Create a button foo with (eg) an x position of 100px
Write some animation that moves foo from 100px to 200px (this could be in script or markup)
Realise you need to shift foo to 110px to accommodate a stylistic change
Now figure out all the places where you need to change 100px to 110px, noting that you can't do a global search-and-replace because 100px could refer to other things as well

Traditionally this kind of problem (known as a "magic number") is solved by using a symbolic constant – we define a placeholder value named (eg) FOO_X and we define it to be 100px. Then everywhere we want to refer to the x location of foo, we use FOO_X rather than 100px. Then if we want to update foo to be at 110px later on, we simply change the definition of FOO_X to be 110px and our work is done.

This is easily done in script (where you have variables) but not so easily done in markup. So, I have written a very simple pre-processor that will take a bunch of macro definitions and replace them in your markup files AND give you a nice script file containing matching declarations to go along with it.

In addition to simple text expansion (FOO_X = 100px) you can also do arithmetic (FOO_X = BAR_X + 100) and indeed perform any kind of processing in your macros because they are all eval-ed at "compile" time. This has made my life a lot easier, especially when I am just testing things out and I need to re-lay-out stuff over and over again.

Attached is a simple project, along with preprocess.js. You run preprocess.js like this:

cscript.exe preprocess.js <defs> <infile> <outfile> [-d]

where:

<defs> is the name of the definitions file, eg "my_definitions.ini"
<infile> is the name of the input file, eg "markup_with_symbolic_names.xmu"
<outfile> is the name of the output file to create, eg "markup.xmu"
The optional –d switch produces a .JS file with the same base name as <defs> containing JScript declarations for all the macros

The definitions file is a simple text file that contains four types of lines:

Empty lines or lines beginning with a semi-colon are ignored (eg, use for comments)
Lines of the format NAME <space> TEXT define NAME to be exactly TEXT
Lines of the format NAME <space> '=' CODE define NAME to be the evaluation of CODE, which can contain references to functions or other NAMEs
Lines of the format '#' CODE run CODE directly without creating any new names (it is assumed the function being called adds names implicitly)

If a macro definition looks like a number, the system will automatically create an additional macro with the same name with "_PX" on the end that has the same value with "px" on the end. An example of a simple file:

; Here is a simple file
; These lines are ignored
; This creates two macros
; The first is called "BUTTON_X" and has the value 100
; The second is called "BUTTON_X_PX" and has the value "100px"

BUTTON_X 100

; This also creates two macros by doing simple arithmetic
; Given the definition of BUTTON_X above, this will produce
; both "BUTTON_Y" with a value of 200
; and "BUTTON_Y_PX" with a value of "200px"

BUTTON_Y = BUTTON_X + 100

; This runs the theoretical function DoSomethingCool, which you
; could add to preprocess.js

#DoSomethingCool()

Note that preprocess.js is not necessarily the best code in the world, nor is it a secure application (it will eval arbitrary input code, so DO NOT USE IT on untrusted definition files!). It was something I threw together and have been iterating on in the normal hacker fashion. It was an itch that needed scratching, not a well-designed and thought-out application.

Also note that whilst using the –d switch will output a script file, it is not big-endian as the HD DVD spec requires! This is due to a limitation in the FileSystemObject. You need to open the JS file in Notepad and re-save it with Big Endian encoding. That's why it isn't generated by default…

So, on to the enclosed example HDi program, it is very simple and very ugly. All it shows you is a simple defs file and a simple input markup file. Running the batch file will create the output markup file and then run the result (assuming HdiSim.exe is in your PATH). Clicking on the blue square makes it grow larger.

AMAZING!

But what is "cool" about this is that if you edit the defs.ini file and change (eg) the SMALL_W_ANIMATED value to 500 (to make the blue button grow larger) and re-run the batch file, the red button will automatically shift as well. No need to go and tweak its values to compensate for changes in the blue button.

AMAZING!

Well, not so much, but in more complicated projects this is a real time-saver.

Script Execution Order in HD DVD

ptorr — Thu, 09 Nov 2006 00:28:00 GMT

An HDi application can use multiple script files so that you can better manage your code (more manageable files; easier source control; etc.). You do this simply by listing the files inside <Script> elements inside the manifest (and of course add the appropriate <Resource> elements if they're not all in an ACA file). Whether or not script code in one file can "see" the script in another file is a common question that I'll address here.

Spec Behaviour

The HD DVD specification says that you take all the script files, load them in the order they are listed in the manifest, and then start running the script engine. This means that you really have one big "virtual file" that is the concatenation of all the individual files, and so all the code can "see" all the other code.

This doesn't mean you're home and dry, of course, because there are some other things to be wary of that we'll get to soon.

HDiSim Behaviour

The spec behaviour was clarified in a fairly recent supplemental change, and so HDiSim currently uses a different approach – it loads each script file and executes it in the order listed in the manifest, similar to how a web browser would load and execute multiple <script> blocks. What this means is that in HDiSim, code can only "see" code in the files that were listed before it in the manifest.

Note that this only applies to "global code" that executes as soon as the script is loaded; basically any code outside of any functions (and the code that it calls, etc.) is subject to this rule, but because ECMAScript is a late-bound language, once all your script files have been loaded and your setMarkupLoadedHandler has been called, all your code can "see" all the other code anyway.

So it's only during initial startup that you have this problem.

Caveats

There are still several things to think about though. First let's look at what happens when an ECMAScript interpreter gets hold of a script. It basically does the following:

Scan the file for variable declarations, and make them available (but with the initial value undefined)
Scan the file for function declarations, and make the Function objects available
Start running program code

This means that you can always call functions declared in the same file, and you can always access variables declared in the same file, but if you access variables before they are initialised you get undefined.

Here's a quick example, using Windows Script Host as an example:

var above = "you see this"
print(above)
print(below)
var below = "you don't see this"
function print(s) { WScript.Echo(String(s)) }

Running this program will print "you see this" and "undefined" on the screen. Note that if you comment out the line "var below=..." you will get a runtime error because below is not declared. ECMAScript lets you assign values to undeclared variables, but you cannot read undeclared variables (in broad terms, they can be l-values but not r-values).

Another HD DVD-specific caveat is that the document object is not available when your script first executes; it doesn't become valid until the markup document has loaded and your setMarkupLoadedHandler function has been called. Because of this, you probably want to avoid running too much code at startup anyway; sooner or later you're going to try and access document, and crash.

Finally, ECMAScript lets you re-define functions (since they are just objects like anything else). Within the same file, the lexically last definition will win, but in the case where you load multiple files independently (ala HDiSim) you could end up running one version of the function from global code inside one file, then re-defining it in a later file and running different code. Don't do that.

The Long and the Short of it

So basically what this means is that for maximum compatibility with the spec and with HDiSim, you should just make sure that your script files are listed in a "reasonable" order in the manifest, and that you don't try to do too much work before setMarkupLoadedHandler is called. At that stage, everything will be available to you.

Also, never re-define functions unless you really know what you are doing.