Displays and Layers: basic concepts

PyProcGame display basics

The Mode architecture of PyProcGame allows every mode to provide a display ‘Layer’ to be shown on the DMD. The Layer should be thought of exactly as the Layer metaphor in Photoshop or other image editing software. The Layer family of classes in PyProcGame represent the various container classes for types of content to be displayed on the DMD, and The ordering of the Layers is dictated by the priority of the Modes, with the highest priority mode (largest number) being the top-most layer and the lowest priority mode would be the bottom-most layer (assuming all layers are opaque).

Modes do not always have a visible component, and do not by default. A mode that does have something to show would create a layer by assigning it’s layer attribute (i.e., self.layer) to some specific instance of a Layer object. The type of layer object you create depends on the type of data you want to place in the Layer.

What’s different in the display framework between PyProcGame and PyProGameHD ??

In PyProcGameHD, traditional DMD support has been removed. If you are running a P3-ROC, you didn’t have it anyway, but if you are a P-ROC user, this means you cannot output to traditional 128×32 DMD displays. That said, you can now very easily output full color graphics to a regular video display device (a 1080p monitor, for example).

SkeletonGame specific conveniences (like using YAML to describe fancy layers with minimal code) is described [on this page].

You can use this document to learn the display in “vanilla” PyProcGame –PyProcGameHD “exclusive” layers are indicated where appropriate. Similarly changes to the functionality of some layers was introduced and those are also indicated here. The biggest changes (i.e., things that might cause existing code to not work or behave differently than expected under the new framework) are:

  1. Alpha support: composite_op='blacksrc' is deprecated at best. Instead, every new layer created (Grouped, Frame, etc) is filled with a transparent color –i.e., (0,0,0,0) of the form (R,G,B,Alpha) where Alpha ranges from 0 (invisible) to 255 (opaque). Before, if you created a layer and did not indicate the blacksrc composite_op you would have expected it to be visibly opaque (though not the same as the flag opaque=True which carries a very different meaning for layers). If you’re wondering why you can now see through your GroupedLayer, that’s why. It also means you should probably set that GroupedLayer to have it’s .opaque property set to True which will both stop the lower layers from being visible by preventing them from even being rendered (saving CPU cycles).

  2. Graphical (animations, frames, fonts) assets must be loaded after the display framework has been initialized. What this means, is that any code that initializes a font at ‘global scope’ (i.e., outside a class body) will cause the code to “blow up” –instead, we provide an assetmanager class (defined in assetmanager.py) and all you have to do is provide a list of assets in the file config/asset_list.yaml and they will be pre-loaded for you when the game is loaded (a graphical progress bar is shown).

  3. Using the assetmanager means that you can refer to an animation (or single frame) by its key via game’s animation dictionary.

Look at the sample asset_list.yaml in the SampleGame/config/ folder. The assetmanager should hopefully make things easier.

Types of Layers and examples of their use:


The simplest of Layers (aside from ‘Layer’ itself) is the Frame layer. This layer is used when you want a mode to show a single image on the dmd. Assuming you already have the image in the correct .dmd format (which can be done using the procgame command-line tools to convert an image to a .dmd, or can be converted from other image formats at runtime). You will need three lines:

Of course, you can consolidate into a single line, if you are so inclined:

In PyProcGameHD you would define the file in the asset_list.yaml and simply refer to the file’s key.
Also, in PyProcGameHD, there is no need to convert animations to DMD format.

The asset_list.yaml might include a few entries. In the following example, an chrome.png is a single image and could be used as the source frame in a frame layer:

The corresponding ‘mode code’ to use chrome as a Frame Layer is:

This is far more complicated than just using the AnimatedLayer object that the assetmanager creates when it pre-loads the content.


The text layer will be used a lot in your games and is the same in any DMD based PyProcGame game. The PyProcGameHD version adds HDTextLayer, and it isn’t drastically different, so we will start with this one.

Typically you will create a textLayer

Many layers support a ‘fill_color’ argument which specifies the background fill to be placed within the
larger layer that contains the desired content. In the regular DMD framework those colors are 0..15,
in the PyProcGameHD framework they are (RED,GREEN,BLUE) tuples with values ranging from 0..255 for each RED,GREEN, and BLUE

There is also a width and height argument that lets you specify the width and height of the layer to be
created. The following example uses width, height and fill_color

Panning Layer (HDVGA Extensions)

Animated Layers

Again, PyProcGameHD and it’s assetmanager should make life easier. It will load the animated gifs indicated in the following examples as animations.

The corresponding ‘mode code’ to use a pre-loaded animation as such, is:

Grouped Layers

Real-world grouped layer

Scripted Layer

Layer from Text

Note: this is NOT supported in the PyProcGameHD Framework!!


Advanced Layers for PyProcGameHD

The following are Layers that are only present in the PyProcGameHD Framework only:

Particle Layer

Rotation Layer

HD Text Layer

Adds borders and interior fill colors

Animated HD Text Layer

Transition Layer

Script-less Layer

Assorted Changes in PyProcGameHD

  1. Added some fixes for when frame_sequences are used. My frame_listeners were not firing when I used frame_sequences, so I added a fix for that.
  2. Added a helper called play_sequence that would play a specific frame_sequence and then revert back to the prior sequence when complete. It makes it more like a traditional animation interface. I also added the ability to send an arg to the listener because I needed that for resuming sequences

  3. Fixed the movie (mp4) layer to work with the new framework. It does now; I’ve tested it.

  4. Added a callback for scripted_layers, so a specified method will be called when that script section is encountered. Example:

  5. Scriptless layer supports callbacks, too

  6. GroupedLayers support a fill_color so that if you want to explicitly black_fill (or something else) you can just specify it here. You can also omit it for the default which is a transparent fill.

  7. PanningLayer supports setting the ‘frame’ content to be any type of layer, so anything can be panned. If you specify a regular frame, well, that still works too. I also fixed some implementation bugs that I encountered with bounce. A ton of testing went on there, so I’d be surprised if any part of that didn’t work.

  8. RotationLayer: a cute toy. Lets you rotate any type of layer. It’s cute.. not very useful but I thought, why not?

  9. I fixed some major placement bugs in AnimatedHDTextLayer that caused them to be positioned incorrectly.