Overview

RP9 files may contain one or more application preview images, for display by playback software and in other contexts (preview thumbnails, directory listings, etc.)

Screen content preview image files must be in PNG format, either with square pixels (1:1 ratio), or in a known platform-specific pixel aspect ratio (e.g. Amiga or C64 PAL or NTSC pixels, with or without line doubling or quadrupling) as described in the XML manifest. Preference should be given to original, unscaled "true pixel" ("1X") screen grabs. Interlaced screen grabs where half of the lines are black or blank should not be used (rather, an original half-frame or deinterlaced bitmap should be captured, with the appropriate ratio attributes). It is important that images consisting of non-square pixels be tagged appropriately, in order to make optimal rendering possible.

The general rule remains that content authors should be strict in the choice of preview image formats, while player applications should be tolerant in the formats they can render.

Player applications will generally render the preview images in the best possible way within a 4:3 ("TV-like") display, which is likely to be sized 160x120 or 320x240 square pixels, or a multiple thereof.

Image Types

This document covers the recommended formats for computer screen preview images. It does not cover box shots, media, label and other images, which may be in different sizes.

Four types of preview images are supported:

• "Running" (memorable "in-game" screenshot)
• "Title" (memorable screenshot where the title is shown)
• "Score" (screenshot showing high store status)
• "Snapshot" (internal use, to visually describe saved states)

Within an RP9 <image> element, these correspond to "type" attribute values "screen-running", "screen-title", "screen-score", "screen-snapshot".

For games and demoscene productions, the default "running" image should be a meaningful and memorable "in-game" shot (not a title screen or box shot).

It is also possible to include a title screen image. For games and demoscene productions, this image should show the title of the application as displayed on screen, or whatever comes closest to it. If present, the title image should ideally be in the same size as the "running" image (which should be present, to support the default preview mode).

Multiple images of each type are supported, each referenced by their own <image> element, and prioritized via the "priority" attribute which ranks the priority within the same type, counting from 1.

Originally, the canonical file names for the (single or primary) "screen-running" and "screen-title" types were "rp9-preview.png" and "rp9-title.png". These names are still desirable, but not required, as they are not hard-coded for recognition purposes.

By default, the highest-priority (lowest number, or as soon as a priority value of "1" is found) image "screen-running" is shown for preview purposes, unless the user has chosen a different preview format (e.g. "screen-title" or dual side-by-side "screen-title" and "screen-running"). For legacy RP9 file support, lacking a description in the XML manifest, "rp9-preview.png" may be used.

Image Color Depth

The color depth of the image should either reflect the original (e.g. palette-based 256 colors or less), or be true color. If the image is resized from the original native bitmap (not recommended), it is highly recommended to convert it to true color before resizing it, and then save it as true color.

At runtime, player systems should be able to always perform an optimal-quality resize. This is especially important for palette-based images, which need to be resized as true-color images. For certain emulated 8-bit systems where different preferences exist to render the respective original analog palette, the player system should be able to detect the original palette colors and correct them to a user-preferred palette (i.e. nearest-neighbor remap or similar) before resizing the image.

Image Size

Recommended square-pixel bitmap sizes are:

• 1024x768 (use only if this is the original "1X" format, not if upscaled)
• 800x600 (use only if this is the original "1X" format, not if upscaled)
• 640x480 (use only if this is the original "1X" format, not if upscaled)
• 320x240 (recommended minimum, unless upscaled)
• 160x120 (insufficient quality on higher-density displays)

Rendered with square pixels (as is common on digital processing and displays), these sizes mirror the shape of the universal 4:3 standard-definition TV format while minimizing the need for subpixel scaling along one or both axes in consideration of common retrogaming resolutions. Both PAL and NTSC televisions had a "4x3 format", independently of the resolution and pixel shape. Implementations like RetroPlatform Player should and will automatically convert between 1024x768, 800x600, 640x480, 320x240 and 160x120 as necessary.

When processing existing images, it may be necessary to take into account ratio distortions and bars at the top and bottom. For example, some popular C64 game screenshot archives use 320x200 images, which is usually based on NTSC data, but can't be rendered properly on 1:1 displays, so it often results in distorted images (circles are not circles any more). Conversely, some popular Amiga archives use 320x256 images, expecting PAL content, and adding black bars at the top or bottom if the source was NTSC.

Image Attributes

Optional attributes make it possible to preserve original pixel-exact bitmaps across different pixel ratios and through simple editing steps such as cropping (e.g. to reduce an overscan area), while providing guidance for preview and viewing purposes:

• Non-zero "left" or "top" attributes indicate an offset that should be discarded for preview and viewing purposes
• Following removal of any top and left offset portions, the "width" and "height" attributes describe the size of the remaining bitmap portion to be retained for preview and viewing purposes
• In the simplest case, "left" and "top" are 0, while "width" and "height" are the same as the bitmap size
• The ratio of the canonical source image pixels (i.e. "TV mode" net of multipliers) is described by the "pixels" attribute: "ntsc", "pal", "square", or "unknown" (which is the default and fallback)
• An additional scaling multiplier used to render the original bitmap in the source environment may be set via the "filter" property: "line-doubler", "line-quadrupler", "horizontal-doubler" or "none" (which is the default and fallback); for example, the bitmap for a Super Hires, non-interlaced Amiga screen mode requires a Line Quadrupler filter in order to be interpreted and displayed correctly, as it was on the original system; a Horizontal Doubler filter would be applied to a bitmap sourced from an interlaced format (e.g. PAL 320x512)

Best Guesses

An automated import procedure that takes into account existing variations could be something like the following:

• If the source is a "double barrel" image (simple check for a frequent scenario: exactly 640x256 with no line-doubler filter specified; longer check: width/height >= 2.5 with no line-doubler or line-quadrupler): the right half is processed into "rp9-preview.png" (unless entirely black), and the left half is processed into "rp9-title.png" (unless entirely black or identical to the right half)
• If the source image is 160x120 or a multiple thereof (e.g. 320x240, 640x480, 800x600) or 1024x768: assume a square pixel aspect ratio unless tagged otherwise
• If the source is exactly 320x200, 320x400, 640x200, 640x400, 704x480, 720x480, 720x486, 1280x200 or 1280x400: assume pixels to be NTSC unless tagged otherwise
• If the source is exactly 320x256, 320x512, 640x256, 640x512, 704x576, 720x576, 1280x256 or 1280x512: assume pixels to be PAL unless tagged otherwise
• If the source is exactly 320x400 or 320x512: assume a horizontal-doubler filter to be required, unless tagged otherwise
• If the source is exactly 640x200, 640x256, 1280x400 or 1280x512: assume line-doubler filter to be required, unless tagged otherwise
• If the source is exactly 1280x200 or 1280x256: assume line-quadrupler filter to be required, unless tagged otherwise
• If the bitmap needs resizing (scaling) to render in the preview area, convert it to true color before resizing it (unless a perfect crop without resize can be achieved); there is always a loss of quality in resizing, so resize only if necessary, and be sure to pick a good resize algorithm (e.g. bicubic)
• If a resize from a non-4:3 ratio source is needed, and no offset hint is provided ("left", "top", "width", "height" attributes), and there are same-color bars at the top and bottom outside of a 4:3 region, cut the central 4:3 part; after this optional step, resize (with stretch, as before) whatever is left to the destination 4:3 pixel size (e.g.  if there are 320x8 bars at the top and bottom of a 320x240 area, remove the bars, and then resize whatever is left)
• If the image is still not 1024x768, 800x600, 640x480, 320x240 or 160x120, crop external same-color (presumed overscan) areas, resize down (maintaining ratio) to 800x600, 640x480, 320x240 or 160x120, and apply black bars to make it exactly 800x600, 640x480, 320x240 or 160x120
• Exceptions: sources known to be NTSC ("tall pixels") or PAL (slightly non-square pixels on most systems) and/or requiring a line-doubler or line-quadrupler filter need to be resized to the square-pixel destination format taking into account their original aspect ratio

The image import feature of RetroPlatform Player (as used in Amiga Forever and C64 Forever 2010.1 and higher) actually employs a similar algorithm when the image is not already in a supported format. The format conversion can also be invoked from the command line:

PlayerName.exe -SetPreview <source.png|bmp|gif|jpg> <destination.png>

In many occasions common sense has to be used, for example because the screenshot contains what should be a circle (which is a good indication of the target ratio), or because stretching can be avoided by just cutting a few scanlines.

Related Links

• RP9 File Format Information