Introduction
Part of the DHGR ToolKit, DHGRRGB is the RGB image converter capable of converting true color 24 BPP images and displaying them on the 128K Apple IIe and //c DHGR screen as a close facsimile to the original. Of course it isn't possible to truly display full color images on the Apple's DHGR screen, but with a clever algorithm we can get pretty good results.
DHGRRGB Tutorial
We will use the pre-installed disk image of PLASMA 2.20 including some samples to play with. First, you will find the DHGRRGB conversion tool in the dhgr.tk/utils directory. There are some sample images already converted into a format digestible to DHGRRGB. But, should you want to format your own image for conversion, here are the simple steps to follow:
Converting a Source Image
- Download and install The Gimp on your modern computer.
- Find a digital image you want to convert.
- Load image into The Gimp.
- Do whatever photo editing operations you want to get the image you want to display, such as cropping. Remember the Apple IIe has a 4:3 aspect ration screen, so don't pick a portrait photo to convert without cropping it first.
- Go to the image scaling dialog box from the
Image==>Scale Image...drop down menu item. - Set the Width to 560 pixels.
- Click the link icon between Width and Height so the image can be scaled to an arbitrary dimension.
- Set the Height to 192 pixels.
- Click the
Scalebutton to re-scale the image. The image must be this dimension or it won't convert. - Make sure the pixel precision is 8 bits from the menu:
Image==>Precision - From the menu:
File==>Export As...to open the dialog box to export the image. - Enter a filename with
.PNMextension. - Ensure the formatting is
Rawwhen theExport as PNMdialog is displayed.
Let's take this image:
It will be scaled to:
Importing Image into the Apple
- Import the
.PNMimage file into a ProDOS disk image. You will need at least an 800K image as the file size is larger than will fit on a 140K 5 1/4 floppy. - Use one of the many tools (CiderPress, AppleCommander) to place the
.PNMimage file. For this tutorial,/PLASMA2/DHGR.TK/UTILS/SAMPLESin the PLASMA-2.20.po disk image.
Converting the Image
- Boot Apple with PLASMA 2.20 environment.
- Navigate to the DHGR Tool Kit Utilities directory:
P DHGR.TK/UTILS - Catalog files in the samples directory:
C SAMPLES - Run converter without parameters:
+DHGRRGBwhich will display the help message:
DHGR RGB converter 1.0
Usage:
DHGRRGB
[-B#] = Brightness: -255..255
[-D] = Dump state
[-E#] = Error strength: 1..255
0 = no err
[-G#] = Gamma: 2, 1, 0, -1, -2
[-M<N,C,P>] = Match: Next, Current
Previous
[-P<I,E,S,N>] = Phase: Ideal, Equal
Simple, NTSC
[-R] = Raw image file, no header
[-S#] = Saturation: -255..255
[-T#] = Tint: -360..360 (in degrees)
[-U<R,G,B>#] = gammUt: Red, Grn, Blu
-255..255
[-V] = no Video output, mem only
IMAGEFILE [DHGRFILE]
- Run a test conversion:
+DHGRRGB SAMPLES/RACECAR.PNM RACECAR.DHGRAt this point it is worthwhile suggesting you run this with an accelerator or in an emulator at its fastest speed.
- An additional speedup (~15%) involves tweaking the JIT compiler settings to include the inner conversion routine as a JIT candidate with:
+JITUNE 32 255. - Should the conversion be taking too long, you can exit early by typing
CTRL-C. - Once the conversion is done, the image will stay on the screen until you press a key.
- Show the converted image:
+DHGRSHOW RACECAR.DHGR
A Note About Emulators and RGB Cards
The Apple II was originally designed to output to NTSC TVs and monitors. It took advantage of the inherent NTSC chroma cycle to create colors through artifacting - outputting a bit stream faster than the chroma cycle frequency. Emulating this feature is hard to get right, but the algorithm employed by DHGRRGB operates on this principle to create the best image. AppleWin has one of the best emulation of a NTSC color TV and composite monitor. If you don't have access to a physical Apple II and CRT monitor, this is the next best thing. Notice the difference between the screen capture above from Virtual II and AppleWin below (exact same image):
Basic Options
- Gamma
The first option to play with is the gamma setting. This setting will quickly darken and image that is too bright and washed out, or bring out the parts of the image that are too dark. It is a non-linear ramp useful for teasing out details. A value of 0 doesn't change the input image at all - a linear ramp. The default gamma setting is 1. To darken our sample image we will use a gamma of 2: +DHGRRGB -G2 SAMPLES/RACECAR.PNM
- Brightness
Each incoming image pixel can be adjusted by a constant amount. Useful for small increases or decreases in brightness across the image.
- Saturation
The saturation option allows for fine tuning of lightness/darkness/saturation. This operates on the calculated chroma RGB values instead of the image RGB values.
- Tint
Tint can be used just like the tint knob on an old TV. It is in degrees. Default is 22 that was determined empirically to best match the NTSC color bars. Try setting it to 180 to create a very odd image.
- Error strength
Error propagation is required to create a high quality conversion of a true color image into a version of only 15 colors. Lower values have more error propagation, starting with 3. 1 and 2 are useless. Values more than 3 start to diminish the amount of error. The default of 4 is is a good start. Decreasing this values will introduce more noise and ringing around high contrast areas. Increasing the error will reduce these artifacts. A value of 0 will disable error propagation all together.
- Raw Image File
Early versions of the converter dispensed with the .PNM file header and used just a raw file of RGB values. Many of those raw files are in the samples directory with the .RGB extension. To convert a raw version of our racecar: +DHGRRG -R SAMPLES/RACECAR.RGB
- no Video output
This doesn't display the conversion to the screen as it happens. This is useful when running DHGRRGB under the portable VM on a modern CPU - orders of magnitude faster.
Advanced Options
Mapping Color Strategy
Use the current chroma cycle to match, the next chroma cycle to match, or default to the running tally of RGB values.
- Phase angles
Use phase angles where red, green and blue are equally spaced around the chroma wheel, at theoretically ideal angles for the Apple II, simplified angles, or default to the NTSC angles.
- color gamUt
Adjust the values of red, green or blue gamma individually: gamma[R,G,B] = gamma[R,G,B] * 128 / (128 - gamut[R,G,B])
Color Matching Strategies
There has been a progression in the development in DHGRRGB starting with the SHR-NTSC TNG project for the IIGS. The idea is to use the actual RGB values previously generated given the limitations of the hardware, and calculate the next best match to the image pixel. What makes this algorithm different is it works at the sub-chroma cycle resolution. This is how artifact colors are generated: a pixel stream coming out of the computer faster than a chroma cycle. In the case of the IIGS, this was an inconvenient 4.57 pixels per chroma cycle using the 640 SHR mode. The DHGR mode uses 4 pixels representing 90 degrees of each chroma cycle, at a horizontal resolution of 560 pixels. This is where the 16 colors (2^4 = 16) at the 140x192 resolution comes from(560/4 = 140). But color isn't actually generated at 140 horizontal pixels like the previous equation may lead you to believe. Each sub cycle in the chroma cycle has an associated RGB value determined by its phase angle into the chroma cycle. The RGB values of the 4 divisions of the chroma cycle are precalculated and can be adjusted with the tint option to shift the resulting colors. Red, green, and blue are centered at given phase angles in the chroma cycle that can also be altered by way of a phase option. There are four options for the RGB phases - the theoretical angles from the NTSC spec (the default), equally spacing RGB at 120 degrees, idealized angles given the four sub cycles of the Apple II, and finally simplified angles that separate green far from red and blue. The RGB values of the chroma cycle should sum to white (255, 255, 255) but can be altered through the saturation option. The color matching is based on only four colors!
The first workable strategy involved using a sliding chroma cycle window to provide a current color. Matching the incoming image pixel along with an error term to the possible current chroma cycle. The current chroma cycle was calculated from summing the three previous sub cycles with the potential of the current sub cycle being one or zero. It is simply a choice between adding the current sub cycle's RGB value or not. This is a quick decision based on the distance between the RGB triplets of the incoming image pixel and the two possible current chroma cycle.
The first epiphany involved increasing the summation of the four previous sub cycles, so the previous full chroma cycle, but scaling the sub cycles towards the most recent. This greatly improved the color matching and fidelity of the resulting image. To generate a proper match, the chroma cycle RGB values had to be scaled appropriately to match the image RGB value. This strategy remains selectable in the advanced options.
The second epiphany involved simplifying the above algorithm even more. Instead of calculating the previous cycle, all the previous sub pixels contribute to a running sum of RGB triplets. When choosing between the two current sub cycle options (0 or 1), 75% of the previous RGB sum is added to the current sub cycle RGB triplet to determine the best match. This is fast, simple, and generates even better images. I, myself, was a bit surprised how well this worked. No scaling of chroma cycle RGB values required. This is the default strategy.
A third strategy is available that turns the best match algorithm around. Instead of looking at the previous chroma cycle, it looks ahead and tries to match the image RGB to the best of the 16 colors. This is a much slower process as it has to do 16 distance calculations per sub cycle pixel. Oddly, this doesn't generate images as good as I would have anticipated. I may revisit this algorithm at a later time to try and improve the results. It is available as an advanced option.
Here are some notes from the source code:
// Bit patterns and associated default NTSC colors
// NTSC_BLACK = 0000
// NTSC_DRKBLUE = 0001 73, 14, 116
// NTSC_DRKGREEN = 0010 0, 104, 100
// NTSC_BROWN = 0100 55, 113, 11
// NTSC_MAGENTA = 1000 127, 23, 27
// NTSC_PURPLE = 1001
// NTSC_MEDBLUE = 0011
// NTSC_LTBLUE = 1011
// NTSC_AQUA = 0111
// NTSC_GREEN = 0110
// NTSC_ORANGE = 1100
// NTSC_PINK = 1101
// NTSC_YELLOW = 1110
// NTSC_WHITE = 1111