Custom Drawing

Some features in PinballY let you do your own custom drawing from Javascript code. This lets you create a custom mix of text and graphics with the precise pixel layout you want. Custom drawing can be used in the following places:

Creating a custom drawing function

The procedure to carry out custom drawing is a little indirect. You can't just execute drawing primitives like "draw a rectangle" from anywhere in Javascript code. Instead, all of your custom drawing code has to be contained within a "custom drawing function". This is just an ordinary Javascript function, with the following signature:

function myDrawingFunction(dc) { // carry out the drawing primitives here }

The name of the function is arbitrary - you can call it anything you want, and you can create as many different drawing functions as you want, all with different names. What's important is that it's a function that takes one parameter, which we've called dc here for "drawing context". The parameter name (like the function name) is up to you, though - you can call it anything you want.

The dc or drawing context argument is a special system object that the system creates and passes to your drawing function when it invokes the function. The drawing context contains the system methods that let you carry out the actual graphic operations, such as drawing rectangles, text, and images. This object is only valid for the duration of the function call to the drawing function, so you shouldn't store it in a global variable or otherwise hang onto it. Treat it as a temporary object that exists for the duration of the function call only.

The system calls this function after setting up the graphics area for the drawing. The argument to the function is a "drawing context" object, which has methods that let you draw text and graphics into the popup area.

Return value from the drawing function

The return value from the drawing function depends on the context where you're using the function:

Drawing context

When the system calls your custom drawing function, it passes in an argument that we call the drawing context. This is a Javascript object that encapsulates the internal drawing surface that all of the graphics primitives operate on. The drawing context provides a set of properties and methods that you call to carry out drawing operations on the drawing surface.

The drawing surface contained in the context is, technically speaking, an in-memory bitmap. More intuitively, it's like opening up a new, blank Photoshop image: it's a drawing canvas with a certain pixel size, and you can use the graphics primitives (the methods on the drawing context object) to paint different sorts of graphics into the blank image.

A drawing context is only valid within the custom drawing function. It stops being usable as soon as the drawing function returns (so you shouldn't store it anywhere global, to avoid accidentally using it in other scripts, where it would cause errors if used).

Color values

Several of the drawing context methods take color values as arguments. You can specify these in several ways:

Default alpha value

For convenience, you don't have to specify the alpha value in each individual color parameter.

The default alpha value is given by the defaultAlpha property of the drawing context. You can read this property to get the current default, and write it to set the new default that will apply to subsequent method calls on the drawing context.

The system always sets defaultAlpha to 0xFF before calling your custom drawing function. (This happens on every call to a custom drawing function, so you don't have to worry about whether other drawing functions that were called before the current one might have changed it.)

Note that if you explicitly want to draw an area with an alpha of 00, meaning fully transparent, you must set defaultAlpha to zero first. Since the system always replaces a zero alpha in a color parameter with the default alpha value, the only way to actually get a zero alpha in the final color setting is to set the default to zero. That will replace the 00 alpha you specify in the color parameter with the 00 in the defaultAlpha property, leaving the zero alpha unchanged for the final coloring.

Text drawing

The drawing context methods below include a number of primitives related to drawing text strings. Those are suitable for simple text displays where you only need to display text in a single style at a time; for simple tasks, they're easy to use and lightweight in terms of performance impact. However, they're not powerful enough for more complex tasks where you want to display text containing a mixture of styles, especially if the text needs to be word-wrapped to display paragraphs or more complex layouts. For something like that, you should instead use StyledText or HtmlLayout. Those classes provide higher-level interfaces for complex text layout tasks, and they both readily inter-operate with the primitives discussed below, so you can freely mix formatted text layouts with the other graphics to build up composite displays.

Drawing context methods

The drawing context has the following methods: