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:

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.

Drawing context methods

The drawing context has the following methods: