Hardware Scaling

The GCW Zero's JZ4770 system on a chip contains an image processing unit (IPU) that can be used to scale the video output of applications to the LCD panel's native resolution of 320x240 without using software algorithms on the main CPU.

Prerequisites
To develop applications that use hardware scaling (and for end-users to be able to use them), make sure you have the GCW Zero firmware, 2014-08-20 or later. You (but not the end-users) will also need the GCW Zero toolchain, 2014-08-20 or later.

Requesting hardware scaling in code
SDL applications may request video modes scaled by hardware using familiar code:

... SDL_Surface* screen = SDL_SetVideoMode(  256 /* width */, 224 /* height */,   16 /* bits per pixel */,   SDL_HWSURFACE | SDL_DOUBLEBUF);
 * 1) include "SDL.h"

The width and height are simply changed to values that are not 320 and 240. The example chosen here, 256x224, appears in PocketSNES when the user has chosen to use hardware scaling.

Upscaling and downscaling
Certain ported games want to use the highest resolution available on the computer running them. This is troublesome if the games support both 640x480 and 320x240 and use software rendering, which would take 4x more CPU time in 640x480 than in 320x240.

For this reason, applications wishing to use, at any time, a resolution over 320x240 need to have this declaration in their .gcw0.desktop file:

X-OD-NeedsDownscaling=true

This will allow your code to request arbitrary resolutions.

During testing (not for your final OPK release), if running bare executables, you can get the effect of the above declaration by issuing the following command over SSH or Telnet: (Note: This path may change in later firmwares. Do not count on it except during testing.)

echo 1 > /sys/devices/platform/jz-lcd.0/allow_downscaling

You only need to run this command once per reboot of the GCW Zero.

Aspect ratio preservation
 + = Toggle aspect ratio preservation

By default, your video mode will be scaled to preserve the aspect ratio. The user will be able to change this to stretch the image to fill his or her GCW Zero's LCD screen with Power+A.

If you are the author of a program that often switches video modes, i.e. an emulator, it will be a great annoyance to users to have to press Power+A every time a new game is launched. You are strongly encouraged to instead add a "Keep Aspect Ratio" option in your program's settings. You can use the following to alter the IPU's current aspect ratio setting after each time you set a new video mode: (Note: This path may change in later firmwares.)

echo 0 > /sys/devices/platform/jz-lcd.0/keep_aspect_ratio

or

echo 1 > /sys/devices/platform/jz-lcd.0/keep_aspect_ratio



Maximum resolution
In the 2014-08-20 firmware, the maximum allowed resolution, regardless of the presence of X-OD-NeedsDownscaling, is 640x480. This is a limitation of OpenDingux's framebuffer driver.

Scaling fractions
The IPU requires that the denominator of the scaling fraction be 32 or below. The IPU driver automatically adjusts the requested scaling ratio so that the denominator is valid. However, this adjustment may pad your image with some columns or rows of black pixels.

To figure out if a certain size is displayed with padding on the GCW Zero's LCD screen, follow these steps:


 * The width scaling fraction is 320 over the width you requested. (For example, 320 over 256.)
 * The height scaling fraction is 240 over the height you requested. (For example, 240 over 224.)
 * Reduce both fractions. (320/256 = 5/4; 240/224 = 15/14)
 * If the denominator of either fraction is over 32, the driver will pad your video output with black pixels. (In this example, no padding is required.)