Plasmacore:Images

From Plasmaworks

Contents 1 Organization 2 Core Image Classes 3 Image Sheet System 3.1 Overview 3.2 Example

Organization

• Place PNG and JPG images in the "images/" folder of your project.
• Your images are automatically arranged on image sheets at compile time. See #Image Sheet System, below, for more information.
• Edit data/image_manifest.txt to customize how images are grouped, to specify that an image is a font strip, and to automatically split tile sheets into separate images.

Core Image Classes

• Primarily you'll use class Image, which loads an image as a hardware-accelerated texture that can be quickly drawn, scaled, and rotated.

• Use CompositeImage to manage splash screens and large background images. Composite images are automatically broken up into 256x256 pixel chunks that easily fit on image sheets.

• You can create an extended CompositeImage class and override the draw_content() method to easily rotate and scale an entire batch of drawing operations.

• An OffscreenBuffer may be rendered to and then used as a typical image.

• Sometimes you'll want to use class Bitmap, which loads an images as a software array of Color pixel values to allow for image preprocessing. Bitmap objects may be easily turned into Image objects ("Image(bmp)").

• Type "gogo doc Bitmap" or "gogo doc Image::draw" (etc.) for documentation.

Image Sheet System

Overview

• At a low level, loading images individually results in generally poor performance due to per-image overhead in several areas: load time, memory, and switching textures during rendering.
• To work around this we can use image sheets (aka texture sheets or texture atlases), which means combining numerous small images together on fewer, larger images.
• Plasmacore has an automatic, mostly transparent image sheet system.
• Every time you "gogo build" or "gogo compile":

1. The file "data/image_manifest.txt" is automatically updated to reflect new or deleted images contained in the "images" folder.
2. Based on the contents of image_manifest.txt, image sheets are compiled from individual images and placed in "build/platform/images".

• You'll want to edit image_manifest.txt to define categories (to ensure certain images are placed on the same texture sheet) and to have the image sheet generator automatically split some images into tiles. image_manifest.txt contains a header comment that describes all the options.
• Here's the general work flow:

1. Place a new image in the images/ folder.
2. Run "gogo compile".
3. Edit "data/image_manifest.txt". The new image filename will be there. Place the filename under a desired category and/or add one of several options for how the image should be handled.
4. In your game, load the image with "Image(original_filename)", "CompositeImage(original_filename)", etc.

• You can have per-platform image manifests using the "platform-x" and "platform-not-x" folder name system - just copy your original manifest into the desired location to begin. For example, compiling for "ios" would look for image manifests in the following order (the folder names are just examples) and use the first one that existed.

1. data/platform-ios-android/image_manifest.txt
2. data/platform-not-windows/image_manifest.txt
3. data/image_manifest.txt

Example

Say our art consists of:

• "actor.png" containing 4 rows of 5 frames each, arranged on an even grid
• "grass.png" containing 8 variations of a grass tile
• "font_game.png" containing a proportional font definition
• "cursor.png" containing a mouse cursor image
• "background.png" containing a background image the game is drawn over.
• "splash.png" containing a full-screen logo.

We put those all in the images folder and "gogo compile" the game. "data/image_manifest.txt" would now contain something like the following (it would list some other details about each image on the line(s) following the image definition but you can ignore those - those are automatically regenerated on every compile):

 [category standalone]
 "font_game.png"
   # The font image is too wide to fit on a 512x512 image sheet so it's placed
   # in the "standalone" category.
 
 [category general]
 "actor.png"
 "grass.png"
 "cursor.png"
 "background.png"
 "splash.png"

At this point:

• • build/platform/images contains "font_game.png" and one or more "image_sheet_general_X.png" (where X is 0, 1, 2...).
  • The splash screen is mixed in with the actor, etc.
  • You could load Image("font_game"), Image("actors"), etc. and they'd be loaded as the original images.

Let's manually reorganize things to be optimal. We'd edit the file to look like this:

 [category standalone]
 "splash.png"
   # Only loaded once so let's not bother to put it on an image sheet.
 
 [category permanent]
 # Anything in category permanent is kept when you call ImageManager.release_all().
 "cursor.png"
   # Load as Image("cursor")
 
 "font_game.png" font
   # Load this one as Font("font_game").
 
 [category gameplay]
 "background.png" composite
   # breaks the bg up into chunks that are easier to arrange
   # Load as CompositeImage("background")
 
 "actor.png" split 5x4
   # Splits the actor into 20 frames.  Load as Image[]("actor").
 
 "grass.png" split 8x1
   # Splits the grass into 8 frames.  Load as Image[]("grass").

Run "gogo compile" one more time and take a look in the build/platform/images folder. You'll see "splash.png", "image_sheet_permanent_0.png", and "image_sheet_gameplay_0.png".