Hardware Scaling

From GCW Zero Wiki
Jump to: navigation, search

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.

Contents

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:

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

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

Power + A Button = 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.

Limitations

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.)

See also