A fixed image feature displays a single, fixed image. The source image can be .png or .jpg. It's placed at an absolute location on the screen, but like any other node it can be moved around the screen by a parent "translate" node.

An image sequence is like an image node, except that it has a sequence of images that are shown, one per frame. This allows one to produce a cel animation. An image sequence can repeat, starting with any frame of the animation.

Two or more image sequences can be linked together so that they share the same frame count. That frame count keeps updating so long as any one of the image sequences are active. This can be used, for example, for two image sequences representing a count down that can be in one of two states. An example of this can be found in this snippet from the "Ryan's Life" show, in AuthoringTools/grin/jdktools/grinviewer/src/com/hdcookbook/grin/test/assets/ryan_show.txt:

    feature assembly F_commentary_menu_count_up {
	    off  F_commentary_menu_count_up_off
	    on   F_commentary_menu_count_up_on
    } ;

    feature image_sequence F_commentary_menu_count_up_off
	    600 0
	    "Menus/CountUp/CountUp_OFF/CountUp_OFF_" {
		ZZ + + + + + + + + + + + + + + + + + + + + + + + +
		00 + + + + + + + + + + + + + + + + + + + + + + + +
		01 + + + + + + + + + + + + + + + + + + + + + + + +
		02 + + + + + + + + + + + + + + + + + + + + + + + +
		03 + + + + + + + + + + + + + + + + + + + + + + + +
		04 + + + + + + + + + + + + + + + + + + + + + + + +
		05 + + + + + + + + + + + + + + + + + + + + + + + +
		06 + + + + + + + + + + + + + + + + + + + + + + + +
		07 + + + + + + + + + + + + + + + + + + + + + + + +
		08 + + + + + + + + + + + + + + + + + + + + + + + +
		09 + + + + + + + + + + + + + + + + + + + + + + + +
	    } ".png" repeat
	    end_commands { segment_done ; }  ;

    feature image_sequence F_commentary_menu_count_up_on
	    600 0
	    "Menus/CountUp/CountUp_ON/CountUp_ON_" {
		ZZ + + + + + + + + + + + + + + + + + + + + + + + +
		00 + + + + + + + + + + + + + + + + + + + + + + + +
		01 + + + + + + + + + + + + + + + + + + + + + + + +
		02 + + + + + + + + + + + + + + + + + + + + + + + +
		03 + + + + + + + + + + + + + + + + + + + + + + + +
		04 + + + + + + + + + + + + + + + + + + + + + + + +
		05 + + + + + + + + + + + + + + + + + + + + + + + +
		06 + + + + + + + + + + + + + + + + + + + + + + + +
		07 + + + + + + + + + + + + + + + + + + + + + + + +
		08 + + + + + + + + + + + + + + + + + + + + + + + +
		09 + + + + + + + + + + + + + + + + + + + + + + + +
	    } ".png" repeat
	    linked_to F_commentary_menu_count_up_off ;

Note the linked_to at the end - this keeps the two image sequences locked on the same frame together, regardless of which one is visible at the time.

A box displays a rectangular box on the screen, with an outline that has rounded corners. It's useful for drawing a highlight around something.

A text feature lets you display text using a font that's either built into the player, or packaged with your xlet. Text can span multiple lines, and the color and alpha level can change over time. You can't mix text styles (e.g. regular, bold or italic) within one text feature, however.

A fade feature will set the alpha level for the drawing of its children. The fade level can vary over time, and a smooth animation effect can be achieved with one of the "tween" functions.

When using the fade feature, you have to understand a little bit about how Personal Basis Profile's java.awt.Grpahics2D class works. The fade feature sets an AlphaComposite on the PBP graphics, then calls its children to draw. After the children are done, it restores the Graphics2D to its former state. This works great, but what happens if one of the children also sets the AlphaComposite? Some other node types do, like src_over and font strip text features.

The answer is that a child node that sets its own AlphaComposite might ignore any AlphaComposite set for it by a parent. This is a consequence of how the PBP graphics API is structured - it would be complex and inefficient to try to compose together a number of graphics effects, and this would be at odds with the GRIN design philosophy of speed and simplicity. So, the rule with Fade is to be careful if you're fading something that includes features that themselves set the AlphaComposite.

A translator moves the position of its children on the screen by a relative delta-x and delta-y. The delta values can be animated over time, and smooth animations can be had with various tweening functions. One interesting application of a translator can be seen in an orbit simulator, built into the "Playground" test xlet (do cd xlets/tests/functional/Playground then ant grinview, then click on S:Initialize and pick number 6). Translators work on pre-computed values linked into a path by linear interpolation, so arbitrary functions can be evauated during authoring and efficiently run on a player -- even Kepler's orbital equations!

A clipped feature clips its children within a clipping rectangle. This can be useful in conjunction with a translator, to make a set of child nodes slide out, for example.

A src_over feature makes its children draw in SRC_OVER drawing mode. Normally, GRIN draws in the more efficient SRC mode, but this doesn't support alpha blending within the Java graphics plane. SRC_OVER mode does, at the cost of some speed. SRC_OVER drawing might be about 33% slower than SRC mode drawing.

Some GRIN node types can support runtime scaling. Images can be scaled, and so can boxes, but text cannot. For this reason, the scaling_model node is not a normal modifier node -- it does not have children whose appearance it modifies, because this can't be supported using PBP's Graphics2D. Rather, the scaling model node type just maintains an x and y scale factor, and an anchor point. The fixed image, image sequence and box features can refer to a scaling model to modify their size and position.

Both the scaling factors and the anchor point can be animated, that is, they can change over time. As with other animated parameters, they can be animated smoothly using tweening functions that are computed at compile time, and represented as a series of linear interpolations at runtime. A nice sample of scaling can be seen in xlets/grin_samples/BouncingReddy. Another good example is in the bookmenu project, when the keyboard used to access bonus content seems to spin around twice, and then expand and fade out.

A group is just a list of child nodes. When a group is made visible, all of its child nodes will be visible.

An assembly is a little bit like a visual "switch" statement. An assembly has a number of child nodes, but only one of the children is active at any one time. Using an assembly, you can switch out what is visible on the screen. Often, the child node that makes up one such assembly part will be a group node. A typical assembly that has three states, called "s1", "s2" and "s3" would look like this:

    feature assembly F:MyAssembly {
	s1	F:GroupOne
	s2	F:GroupTwo
	s3	F:GroupThree
    } ;

Assemblies might seem unfamiliar if you're coming from a background of UI widgets, but they are one of the most commonly used idioms in GRIN. Assemblies let you manage the state of the user interface in a purely declarative way.

As you can see from the runtime class name, a menu assembly is really just syntactic sugar for a normal assembly. We noticed that a normal assembly could get verbose for normal menus. For example, consider a three-button menu, where a button can be normal, selected, or activated. This turns into a six-part assembly that looks something like this:

    feature assembly F:MyMenu {
	b1_sel		... a group with button 1 showing selected ...
	b1_act		... a group with button 1 showing activated ...
	b2_sel		... a group with button 2 showing selected ...
	b2_act		... a group with button 2 showing activated ...
	b3_sel		... a group with button 3 showing selected ...
	b3_act		... a group with button 4 showing activated ...
    }

With a menu assembly, you first declare a "template" group that has all of the buttons in the normal state. Then, for each real state of the assembly (e.g. the six states above), you specify which parts of the template get overridden, and what they get overridden with. When the show file is read in (by the compiler or by grinview), the menu_assembly is turned into the equivalent normal assembly.

Please refer to the show file syntax (search for "menu_assembly ::=") for the syntax used to specify this. You can also find an example in xlets/hdcookbook_discimage/bookmenu/src/com/hdcookbook/bookmenu/assets/menu.txt.

A timer isn't quite a structural feature, but it doesn't really belong anywhere else in the taxonomy, so we put it here. A timer is a feature that counts how many frames happen while it's active, and after a certain number of frames has gone by, it triggers a command. Many other features can trigger commands, too - most of the features described above that do some animation can trigger a command when the animation is done. Commands are discussed further down in this document.

A "command" RC handler just triggers a command when a certain remote control key press (or key release) is detected. In it's simplest form, it can be used for a screen that says "Press OK to continue" - for this, you'd have a command RC handler that, when OK is pressed, would do something like move to another segment.

A "visual" remote control handler is really quite sophisticated. It's usually used in conjunction with an assembly. In a visual RC handler, you specify a rectangular grid of state names. By default, the arrow keys move you within this state grid, though you can also modify what any given key does from any given state. Having a grid like this lets you set up many navigation schemes simply, by just organizing the state names correctly. A positon on the grid can be a state, or it can be a "forwarding reference" to a state somewhere else on the grid.

Usually, you'll link a visual RC handler to an assembly. Each state on the state grid will map to two states in the assembly, one for selected (when you navigate to that state), and one for activated (when you press OK). You can also trigger commands on the various state transitions. Finally, you can declare rectagular areas on the screen, where mouse entry goes to a "select" state, and mouse click goes to an "activated" state. Please refer to the show file syntax (search for "visual_rc_handler") for the syntax used to specify this. You can also find several examples of the use of visual RC handlers in xlets/hdcookbook_discimage/bookmenu/src/com/hdcookbook/bookmenu/assets/menu.txt.

An activate segment command moves the show from one segment to another.

An activate part command is used to change the state of an assembly. Remember, assemblies have exactly one active part at any given time. This command can change which part is active.

A segment done command causes a segment to queue the commands in its segment_done clause. They'll go to the end of the command queue, and be executed before the next frame of animation displays. Segement done commands are a convenient way of structuring a show, by putting activate segment commands in a segment's segment_done clause to chain a number of segments together.

This command sets the state of a visual RC handler. It's often used to initialize a visual RC hanlder to a known state. It will often appear in the on_entry clause of a segment that contains a visual RC handler, in order to initialize the hander.

Note, however, that a visual RC handler also initializes its internal state from the assembly it's linked to, if it's lined to an assembly. For such RC handlers, if you want to initialize the UI's state on entry to a segment, you will most likely want to use an activate_part command to initialize the assembly.

A reset feature command will reset a feature. It has the same effect on that feature as would happen if the feature were de-activated and then activated again. For example, an image sequence resets to the first image in the sequence, and other animating nodes reset back to their first frame, too.

A sync display command suspends processing of the command queue until at least one frame of animation has been displayed to the screen. This can be useful to do just before launching a CPU-intensive operation, like selecting a playlist. Without a sync display command, the screen might "stick" on an intermediate point of the animation (e.g. before a button is shown as activated), and it might stay there for a second or two as the playlist is selected.

The GRIN file syntax lets you give a name to a list of commands. Within the show, you can run that named list. This can be useful for repetitive stirngs of commands. It can also be useful for scripting from Java, because Java can look up the command list object by name, and then trigger those commands from code by calling Show.runCommand(Command).

The GRIN compiler that parses a show file, and turns it into a compact and efficient binary file. Parsing is much slower than reading a binary file, so this produces a valuable speed-up in xlet initialization. The GRIN binary file usually has an extension of .grin, or .grn if you need to store it in an 8.3 filesystem (like the BD-J BUDA).

In a GRIN show, any feature can only be displayed once at a given time. That is, a feature like a fixed_image can't appear in two different places on the screen simultaneously, so for that reason it's illegal for the same feature to appear twice in a group. This constraint is needed due to the way optimized drawing works -- it allows an efficient implementation that doesn't require dynamic memory allocation during the animation loop.

Note, however, that the same feature can appear in two different segments, or in two different parts of an assembly. Indeed, the GRIN scene graph of features is not a tree, it's a directed acyclic graph. Even so, the constraint that the same feature can't be active through two different paths at any given time must be respected.

This is done automatically by the GRIN compiler, so if you make a show that has this structural problem, it will be reported as an error. If you'd like to see how it's done, look to the class com.hdcookbook.grin.SEDoubleUseChecker.

As described in the HD cookbook, the GRIN compiler can also assemble a number of small images into a matrix of images contained in one large image. Doing this makes the images load much more quickly. Measurements indicate that there's no noticable degredation in display speed whe this technique is used.

Which images are grouped together can be important, particularly when you're optimizing startup and image load time, and when you're managing pixmap memory. The preferred syntax for managing image mosaics in GRIN is to have a single mosaics file for the xlet. This can combine images from several GRIN shows - you just compile all of the shows along with the mosaics file in one invocation of the GRIN compiler, and it generates the .grin binary files, the mosaics, and the data files that say which image was put where.

For the syntax of the mosaics file, search for "mosaics ::=" in the show file syntax.

The GRIN compiler accepts x and y scale arguments (-scaleX double and -scaleY double). When a show is scaled, all of its features are reduced or expanded by the scale factor. Because there's a different X and Y scale factor, you can even change a show at a resolution with square pixels (e.g. full HD, 720p or QHD) to one with non-square pixels (e.g. NTSC SD at 16x9). A sample xlet that does this can be found at xlets/tests/functional/ScaleBunny, which is the GrinBunny game re-written to run at different screen resolutions.

When the features are scaled, the image assets aren't necessarily scaled. Images are only scaled down to the size of the largest size within a fixed image or image sequence feature. Thus, if a normal full HD show contains a 200x200 image that it statically scales up to 400x400 (using the scale option of the image_placement), then when that show is scaled down to QHD, the image will be left at 200x200. Of course, this only applies to static image scaling - the grin compiler doesn't try to figure out what your scale_model might do.

Font strips allow you to pre-render the characters you want into a single .png file, and then display strings using those images. This feature is described in some detail in the file AuthoringTools/grin/extensions/fontstrip/README.txt. Note that the font strip text feature sets SRC_OVER drawing mode. If you're using a font strip text feature that's under a fade node, be sure to read "A word about alpha blending" in the fontstrip README.

The com.hdcookbook.grin.media standard extension package includes a simple media player to play a playlist. As of this writing, it's not very extensive -- it lets you start and stop playback of a playlist, but it doesn't address more advanced media features, like triggers tied to the media timeline, video scaling, or trick play. The media player does demonstrate a good model for linking media to a show, using GRIN commands for callbacks when media events happen.

The media extension is used in GrinBunny to show the starfield video in the background.

The set_target feature is a modifier - it causes the drawing of its child nodes to be directed to a different "drawing target". Within the child nodes there can be another set_target node, which overrides the draw target setting for that sub-node's children.

A drawing target is used to group drawing operations that are expected to be in the same area of the screen. The animation framework makes a bounding rectangle around all of the changed areas withing each drawing target, and then it optimally combines the rectangles from each drawing target. This makes it possible to minimize the area in the screen that is painted to. As a rule of thumb, one probably shouldn't have more than four or five different draw targets.

For more information about optimized drawing, see the description of the animation framework, particularly the "Optimized Drawing" section.

A guarantee fill node supplies a small optimization to the animation process. It relies on the following insight: If a rectangular area is filled with SRC mode drawing, then there is no need to erase any pixels within that rectangular area. A guarantee_fill node can be put in the scene graph to tell the animation framework that erasing the given area in the off-screen buffer is not needed, presumably because some other visible feature or set of features completely fills all of the pixels within the designated area.