HAMLAB PLUS 2.1.0 USER'S MANUAL (c) Copyright 1990-1992 J. E. Hanway All rights reserved. IN THIS DOCUMENT: SETUP SYSTEM REQUIREMENTS INSTALLATION CONFIGURATION ADDING NEW FILTERS AND EXPORTERS QUICK START USER INTERFACE REFERENCE COMMAND LINE OPTIONS ENVIRONMENT VARIABLE WORKBENCH TOOLTYPES THE MAIN WINDOW THE ABOUT WINDOW THE CONFIGURATION WINDOW THE COLOR CONTROL WINDOW THE OUTPUT MODE WINDOW THE AREXX CONSOLE AREXX FUNCTION KEYS THE HAMLAB PLUS PIPELINE AND CACHES SETUP SYSTEM REQUIREMENTS HAMLAB PLUS runs on any Amiga, under either release 1.3 or 2.0 of the Amiga operating system. At least 1 meg of RAM is required. For full functionality, HAMLAB PLUS requires EITHER AmigaOS Release 2 OR AmigaOS 1.3 and the ARP library. If you have neither the ARP library nor Release 2, you can still run HAMLAB PLUS, with two limitations: It will only have a poor excuse for a file requester. HAMLAB 1.x input filters cannot be used. In any case, only the ARP library itself (LIBS:arp.library) is used. The ARP commands in C: do not need to be installed. ARP is not required for operation under AmigaOS Release 2. In order to use HAMLAB 1.x input filters, HAMLAB PLUS requires the AmigaDOS PIPE: device. Different versions of PIPE: are supplied with 1.3 and 2.0. If you encounter problems, check your DEVS:mountlist file to make sure that the correct version is used. The 1.3 PIPE: entry should reference "l:pipe-handler" while the 2.0 entry should reference "l:queue-handler" NOTE: You must have mathtrans.library in your LIBS: directory. INSTALLATION Installing a working copy of HAMLAB PLUS on your disk: 1. Decide where you'd like to install HAMLAB PLUS, creating a new drawer if necessary. 2. Copy the following from the original HAMLAB PLUS disk to the drawer that you chose in the last step. (Just drag icons in the Workbench, or use the CLI.) The "HamLabPlus" program. The "HamLab.config" file. (*) The "Filters" drawer. (This contains filters and exporters.) The "Curves" drawer. (This contains color response curves.) (*) If you intend to run HAMLAB PLUS only from the Workbench, just place the HamLab.config icon in the same drawer as the program. Otherwise, move it to either the S: or the DEVS: directory. 3. (optional) Copy the following, if you wish: The "Documentation" drawer. The "Rexx" drawer. (This contains example AREXX scripts. To use them, they must be copied to the directory where REXX: is assigned.) 4. Run the HAMLAB PLUS copy you just made. A "HamLab Config Problem" requester may be displayed. If so, just click the "Ok" button until the main window appears. 5. Click the "Configuration..." button to open the Config window. 6. In the "Filter Path" line, enter the full path name of the filters drawer. 7. Drag the Config window to the upper left corner of the screen. This will prevent it from opening every time you run the program. 8. Click the "Save All" button. This will display a file requester with the name of your default config file filled in. Confirm the save. 9. Close the main window to exit the program. 10.Run HAMLAB PLUS again. This time the "Config Problem" requester should not appear. If it does, double check the "Filter Path" entry and make sure that the config file is being saved in the correct directory. Installing other files: ARP library The ARP library is not used if you are running AmigaOS Release 2. If you are running AmigaOS 1.3 and don't have ARP, copy arp.library from the libs directory of the HAMLAB PLUS disk to the LIBS: directory of your boot disk. If you obtained HAMLAB PLUS as a demo version from a source of freely distributable software, look there for ARP version 1.3. PIPE: device The PIPE: device is supplied as a standard part of both 1.3 and 2.0. So unless you've explicitly taken it out of your system, you already have it. If you need to replace it, you'll have to go back to your original AmigaDOS disks to get the correct entry for DEVS:mountlist, plus the proper handler file for the L: directory. For 1.3, the handler is named "pipe-handler" and for 2.0 it is named "queue-handler". Finally, somewhere in your s:startup-sequence or user-startup, you should have a "mount PIPE:" command. CONFIGURATION When HAMLAB PLUS is run, it loads its configuration information from a "config file." The config file is named "HamLab.config" and HAMLAB PLUS will look for it in the following places, in order: the current directory S: DEVS: The config file contains the following types of information: Directory names where HAMLAB PLUS creates or looks for files (filter programs and temporary files, for example) Information about filter and exporter programs that are installed. Positions for all HAMLAB PLUS windows, and/or whether they should open when the program is started. How much memory and/or disk space HAMLAB PLUS can use. Initial selections for all settings (resolution, size, dithering, etc.). When first installing HAMLAB PLUS, the most important things to get configured correctly are the filters. Without them, HAMLAB PLUS is unable to read any images. Once you have followed the installation instructions, the config file will be updated so that filters will be found in the correct directory and will be known to HAMLAB PLUS. Later, you'll probably want to tailor its memory and disk usage to your system. See the section on caches for more information. The config file is a text file that can be customized with a text editor, but editing it by hand isn't required. The easiest way to create or update a config file is to run HAMLAB PLUS, set everything up the way you like it, and select either "Save" or "Save All" in the configuration window. "Save" saves only settings that correspond to different types of images (resolution, dithering, etc.). For example, you may have one group of settings for hi-res images, and another for low-res ones. "Save All" saves all settings (except cropping, which is always reset for each picture) and is suitable for creating or updating your master HamLab.config file. Of course, you can create config files by hand that have any number of settings in them. See the separate document "cmd-ref.doc" for more details on the config file format. ADDING NEW FILTERS AND EXPORTERS From time to time new filters and exports may be released for HAMLAB PLUS. In order to use a new filter, you must first update the HamLab.config file so that HAMLAB PLUS knows about it. Perform the following steps to do so: 1. Copy the new filter to the HamLab filters directory. (If you followed the standard installation, the filters directory should be a drawer named "Filters") 2. Run HAMLAB PLUS and bring up the Configuration window. 3. Select "Scan Filters." This will test every program in the filters directory to see if it is a filter or exporter and, if it is, what its characteristics are. 4. When the scanning process completes, move the config window to the upper left corner of the screen (to prevent its position from being saved) and select "Save All." QUICK START HAMLAB PLUS can be started from the CLI or by double-clicking its Workbench icon. The six large buttons at the bottom of the main window control the major functions of HAMLAB PLUS. OPEN an image to begin working on it. This will attempt to identify it, and read enough of it to determine its size. Once opened, you can adjust HAMLAB PLUS's settings and execute one or more of the three main functions as follows. EXPORT reads the image, converts it to 24 bits, crops, scales, and color corrects it, then saves it in a 24-bit format. Hitting the EXPORT button displays a list of formats that can be exported. DISPLAY reads the image, converts it to 24 bits, crops, scales, color corrects it, then reduces it to a displayable format and displays the image on the screen. The displayable format can be controlled by bringing up the Output Mode window with the "Change Output Mode..." button and changing the settings before hitting DISPLAY or SAVE. SAVE reads the image, converts it to 24 bits, crops, scales, color corrects it, then reduces it to a displayable format and saves it as an IFF file. The remaining main buttons do the following: REVERT resets all settings to what they were for the last EXPORT, DISPLAY, or SAVE operation you attempted. CLEAR unloads the current image and frees any temporary memory or disk space associated with it. Other windows: The Output window lets you change the mode used to display and save images. The Color Control window lets you adjust "color response curves" used by HAMLAB PLUS for color correction. You can modify the curves by drawing them by hand, or use the controls for brightness, contrast, and gamma. The Configuration window lets you change some basic features of how HAMLAB PLUS operates, such as how much and what kind of storage is used for temporary data. USER INTERFACE REFERENCE COMMAND LINE OPTIONS HamLab Plus understands the following command line options: (You don't have to enter them in upper case.) PORTNAME Sets the base name for HAMLAB PLUS's AREXX port. The default is HAMLAB, and HAMLAB PLUS will add a suffix to that so that the first copy of HAMLAB PLUS running will have a port named HAMLAB.1, the second will be HAMLAB.2, and so on. This name is also used for HAMLAB PLUS's public screen, if you tell it to make one (see below). SETTINGS Specifies the filename of a HAMLAB PLUS config file to be read in after the default config file. Note that this is read in addition to--not instead of--the default config file. STARTUP Specifies the filename of an AREXX script to be run whenever HAMLAB PLUS starts up. PUBSCREEN (AmigaOS Release 2 only) Specifies the name of a public screen where HAMLAB PLUS will open its windows. The public screen must already be open. By default HAMLAB PLUS uses the Workbench screen. SCREEN Forces HAMLAB PLUS to open a new screen for its windows. is made up of one or more keywords, separated by slashes, and without any spaces between them. The valid keywords are: LACE forces the screen to be interlaced NOLACE forces the screen not to be interlaced PUBLIC makes the screen public (AmigaOS Release 2 only) The name specified by PORTNAME will be used as the public screen name. (Or HAMLAB will be used if you don't specify a name.) COLORS allows you to specify the four colors to be used on the HAMLAB PLUS screen. The colors are specified as three hex digits (0-f) each (r, g, b), and each color is separated by a slash. If you are running AmigaOS 1.3, and you tell HAMLAB PLUS to open a new screen without specifying the colors to use, HAMLAB PLUS will use colors close to the default 2.0 colors. If you are running AmigaOS Release 2 and don't specify the colors, HAMLAB PLUS will copy them from the Workbench screen. HAMLAB PLUS doesn't allow a lot of screen options. The size will always be cloned from the Workbench screen (adjusted by LACE or NOLACE), and the depth will always be 2 bit planes (4 colors). If neither LACE nor NOLACE are specified, the screen will use the current Workbench screen's interlace setting. Example: SCREEN LACE/PUBLIC/COLORS/000/fff/aaa/69b CONVERT This option causes HAMLAB PLUS to be run in "simple batch mode." In this mode, HAMLAB PLUS will attempt to load and save each file that matches the AmigaDOS wild card pattern(s) you enter. When all files are processed, HAMLAB PLUS will exit. You will not be able to change any HAMLAB PLUS settings during the batch operation. The only way to control them is to load them from a config file before the batch starts. (This is where the SETTINGS option is useful.) Each converted file will be saved in the output directory specified in your configuration file. CONVERT must always be the last option on the command line. The rest of the command line is treated as filename patterns for the CONVERT process. Command line examples: 1> HamLabPlus PORTNAME HLPLUS SCREEN LACE 1> HamLabPlus SETTINGS hires.config CONVERT incoming:#?.gif ENVIRONMENT VARIABLE (AmigaOS 2.x ONLY) Under AmigaOS 2.x, you can use the SetEnv CLI command to put common HAMLAB PLUS command line options into the HAMLABARGS variable. For example: 1> SetEnv HAMLABARGS PUBSCREEN MyPublicScreen 1> HamLabPlus [hl+ opens on MyPublicScreen] WORKBENCH TOOLTYPES You can also enter HAMLAB PLUS command line options as tool types in HAMLAB PLUS's icon. You should note the following: Tool type keywords should be in upper case. Only one keyword can be entered per line. The keyword must be followed by an equals sign and a value. (For keywords that take no value, just enter a space.) Examples: PORTNAME=HLPLUS SCREEN=LACE/PUBLIC/COLORS/000/fff/aaa/69b THE MAIN WINDOW The main window is always visible when HAMLAB PLUS is running. There are two text display areas across the top of the main window, labeled "Input" and "Output." These display the name, size, and format of the input and output images, respectively. Between the two text areas is a column of four buttons, each of which brings up another window full of controls. One thing to note: these windows are "modeless," which means that you can still use any other window while they are open. If you have enough screen space, you may find room to arrange them the most commonly used windows are all accessable at the same time. The "Change Output Mode..." button below the "Output" area brings up another control window. The next row of controls in the main window is for HAMLAB PLUS's cropping and scaling features. Cropping Cropping cuts out a rectangular area of an image and is useful for removing borders or working on pieces of a large image. HAMLAB PLUS can crop an image twice: once as it reads the original image from disk ("input cropping") and once as it saves or displays an image ("output cropping"). There are advantages and disadvantages to both: the earlier an image is cropped, the less memory and time later operations will take. On the other hand, the later an image is cropped, the fewer steps have to be recalculated if the cropping is changed. In general, input cropping is useful for working on small sections of very large images, which may be impractical to process as a whole due to excessive memory requirements or long processing time. Output cropping is useful for adjusting the borders of an image. Input and Output crop share the same keyboard shortcuts. The I and O keys will switch the other shortcut key meanings from one type of cropping to the other. (The underlines on the screen show the current shortcuts.) Both cropping control areas allow you to define the cropping area by entering the width and height of the cropped area, and/or entering the upper left "UL" and lower right "LR" corners of the cropping area. You can reset a cropping area to the full image size with the "Full Size" button. In addition, while displaying an image, you can define a new Output Crop area by holding down the shift key and holding down the left mouse button to drag a rectangle on the screen. When you release the mouse button, the screen will be closed and the new cropping area will be entered into the gadgets. If you then hit the Display button, it will reselect a palette and display the cropped area. Scaling Between the two cropping controls is the scaling control area. HAMLAB PLUS can scale in image independently in the X and Y directions to anything from 10% to 1000% of its original size. You can scale an image either by percentages or by the desired output size. The "%" buttons allow you to control this independently for X and Y scaling. The ">>" buttons cycle through a few commonly used scaling values as follows: X: 50%, 100% Y: 50%, 100%, 200% These scaling values are also coded to run faster than other values. The "Constrained" setting causes one scaling factor to change when you change the other. For example, if you double the X scaling value, the Y scaling value would double, too. Messages Extending across the width of the main window is a three line message area where informational and error messages from different operations will be displayed. Older messages will scroll off the top. Main Buttons Finally, we get to the main functions of HAMLAB PLUS. These six large buttons at the bottom of the main window control the main functions. OPEN This function brings up a file requester, allowing you to select a file. HAMLAB PLUS will attempt to identify the file and, if successful, load an input filter program, which will start processing the file and return some basic information about the size and (optionally) the depth of the image. Occasionally, some additional buffering must be done by the input filter. This usually occurs when the image is stored in some kind of order other than the top-to-bottom scanline order that HAMLAB PLUS expects. If buffering is needed, a progress window will indicate the progress of the buffering and allow you to cancel it. There are two kinds of HamLab filters: "new" filters for HamLab 2.x "old" filters for HamLab 1.x (will work with HamLab 2.x) New filters have lower overhead than old filters and should generally be faster. They also provide HAMLAB PLUS with more information. For example, old filters cannot send messages to the HAMLAB PLUS window. EXPORT This function allows HAMLAB PLUS to export 24-bit data, after it has been scaled and color-corrected, through a separate "exporter" program, which can save it in some 24-bit format. The export button brings up a scrolling list, from which you pick the exporter you wish to use. HAMLAB PLUS will run that exporter program, which will usually display a file requester, allowing you to choose the name of the file to be saved. A progress window indicates the progress of the export function and allows you to cancel it. DISPLAY This button starts the display operation. Depending on your settings, a great deal of calculations may be required to go from the original image to something that can be displayed, so this function can take a while. As usual, a progress window is displayed, giving you a chance to cancel the operation. Once HAMLAB PLUS has done enough calculating to start displaying data, it will bring a display screen to the front and start rendering into it. You don't have to wait for rendering to complete before you can abort, pan, crop, or start saving the display. HAMLAB PLUS uses two memory or disk "caches" to save intermediate results from prior operations, to minimize unnecessary recalculation. Cache controls are explained later. Closing the Display To close the display, click the right mouse button or press the space bar in the display screen. Panning the Display To pan the display (i.e. scroll to a different area of the image), either use the arrow keys or press and hold the left mouse button and drag in the direction to pan. Cropping the Display To crop the display, press and hold the shift key. (The cursor will turn into a cross-hair.) Then position the mouse to one corner of the desired cropped area, press and hold the left mouse button, and drag out a rectangle to the other corner. When you release the mouse button, the display will close and the output cropping area will be updated. If you release the shift key before the mouse button, the crop operation will be canceled. Saving from the Display As long as the display screen is open, you can save its contents very quickly because no additional rendering calculations are required. You may even start saving the picture before it has completed displaying by pressing the 'S' key in the display window. This will bring up the usual save file requester, then the save operation will catch up to the display. After that, each line will be displayed and saved at the same time. SAVE This button starts the save operation. It first brings up a file requester to allow you to specify the name of the file to be saved. Like the display operation, the amount of processing required may vary depending on how your caches are configured and how many settings you've changed since the last operation. REVERT This button reverts all settings to those which were used the last time you successfully displayed, saved, or exported an image. It is useful if you accidentally change a setting that would cause everything to be recalculated. CLEAR This button releases all memory and/or temporary disk files associated with the current image, and unloads the input filter program. THE ABOUT WINDOW This window displays some copyright and version information, plus it also displays the amount of free memory (as two numbers: chip / fast), the amount of storage in use (two numbers: memory (fast) and temporary disk space), and the current AREXX port ID. Note that the amount of storage in use is only what is in use by the caches, if any. This doesn't count anything like CHIP memory used for a display, or any of the many short-lived buffers that HAMLAB PLUS will use for its processing. THE CONFIGURATION WINDOW This window allows you to control some miscellaneous configuration items. Fix HAM Scrolling Turning this setting on will make HAM images larger than the screen more usable by fixing the glitches that develop down the left edge of the image if you scroll the picture so that real left edge of the image is not visible. This option will slow down scrolling somewhat. This option does not affect the way an image is saved, only how it is displayed. Beep after long functions This setting will cause HAMLAB PLUS to beep and flash the screen after a Display, Save, or Export function has completed. Ask before abandon Turning this setting on will suppress the "Abandon current image?" requesters that would normally apper if you are about to discard all your work on an image without saving it. 12-bit cache This setting controls the maximum allowable size of 12-bit image data that will be kept in memory or on disk. Two numbers are entered here, separated by a slash. The first is the maximum size of a memory cache. The second is the maximum size of a temporary disk file. Both sizes are in bytes. HAMLAB PLUS needs two bytes for every pixel of in a 12-bit cache. You may set either or both sizes to zero. This won't require any memory, but will mean that every pass will require more calculations because HAMLAB PLUS must restart earlier in the process. 24-bit cache This setting controls the maximum allowable size of the 24-bit image data that will be kept in memory or on disk. As above, the two numbers control the maximum memory and disk size in bytes. HAMLAB PLUS needs 3 bytes for each pixel in a 24-bit cache. For more information about how the caches are used, see THE HAMLAB PLUS PIPELINE later in this document. Note: Both caches will attempt to use a single large block of memory. If you wish to keep your caches in memory, but don't have large enough areas available, consider setting the temporary path to the RAM disk and use "disk" caches instead. Temporary path This setting specifies the directory where temporary disk cache files will be stored. Filter path This setting specifies the directory where filters and exporters are located. Pipe device This setting specifies the name of the pipe device. The pipe device is only used when reading an image with a HamLab 1.x ("old") input filter. Normally this should be set to "PIPE:" but you may wish to use a different named pipe device for improved performance. AREXX console This setting specifies the console window to be used for AREXX. A console window specification looks like: CON:left/top/width/height/title/flags See "Using the Amiga System Software" (the AmigaDOS User's Manual) for more information on how to specify a console window. Load Displays the file requester and allows you to select a new config file for loading. All commands in the config file will be applied, and the associated settings will be changed. Note that a config file can change any number of settings, so the "Load" operation does not reset everything before loading a new configuration. Save Saves some of the current values (generally those in the output window) to a new config file. See the command reference docs for information on exactly which settings are saved. In general, this command saves the settings that are likely to change from image to image. It is appropriate for defining commonly used groups of settings. Save All Saves all current values (except cropping, which is reset when a new picture is opened) to a new config file. This command saves everything including the more permanent configuration settings, i.e. the ones that you rarely change. It is appropriate for updating your main config file. Scan Filters This function scans the directory specified by the "Filter Path" setting for HamLab filters (new style only) and exporters. For each filter or exporter program it finds, the program will be automatically queried and the information that it returns will be stored just as if it had been read from a config file. The procedure to add new filters and exporters is simple: drop the filter into the filterpath directory, run HamLab Plus, click on "Scan Filters," then click on "Save All" and replace the old config file. THE COLOR CONTROL WINDOW HAMLAB PLUS can apply color correction to an image using "color response curves." These "curves" are really look-up tables that apply separately to the 8-bit red, green, and blue values that make up a 24-bit image. By default, the color response curves map each input value to an identical output value (0 -> 0, 1 -> 1, 2 -> 2, ...) so that they have no effect. Changing that mapping allows you to control things like brightness and contrast independently for red, green, and blue. The color control window allows you to manipulate the color response curves. You can draw the curves by hand, or use the controls in this window to modify them The three buttons above each curve control which curves are active. Only active curves can be drawn into or affected by the controls. Note that when you draw in one active area, all active curves are affected. Contrast This controls the slope of the active curve(s). A steeper slope results in a more contrasty image. ('+' means "make steeper") Brightness This moves the active curve(s) up and down without changing slope. Moving a curve up will increase the brightness of the image. Gamma This modifies the active curve(s) in a nonlinear fashion. 'C' stands for Compensate, and 'U' for Uncompensate. These buttons will modify the curve by the factor to their right, which can be any number between 0.1 and 9.9. (You must enter a digit, period, digit here.) Compensating with a gamma greater than one will tend to increase the contrast of darker areas while decreasing the contrast of lighter areas. This can do wonders to bring out details lost in shadow without destroying the brighter areas of an image. Uncompensating with a gamma greater than one will have the opposite effect: contrast in shadows will be diminished, while contrast in highlights will be enhanced. Negate This turns all active curve(s) upside-down, resulting in output that looks like a photographic negative. A nice gee-whiz feature, but probably not terribly useful. Smooth This button smooths out some of the bumps in the active curve(s). You can hold this button down and the curves will get progressively smoother. Init This button resets all active curves to initial 45-degree line, so that they basically have no effect on the image. Load This button allows the active curve(s) to be loaded from disk. They can be loaded from either a HamLab format text file, or from the CLUT chunks of some 24-bit IFF files. Save This button saves ALL curves (not just the active ones) to a HamLab format text file. Monotonic This button will fill in the holes in the active curve(s) so that the curve is either always increasing or always decreasing. In other words, it prevents the same curve from going both up and down. Step Size This setting controls how "fast" the contrast and brightness controls work. The higher the number selected, the faster (but coarser) they work. THE OUTPUT MODE WINDOW This window controls all of the different output options of HAMLAB PLUS. One thing to note: the "Output" text area in the main window displays a "shorthand" version of most of the information in this window. Some controls should be obvious: resolution, interlace, and bit planes are all straightforward. Illegal combinations like hi-res HAM are not allowed. Palette Mode The palette mode controls whether this is a normal image (i.e. one palette is chosen for the whole image), or whether the image is "sliced," which means that the Amiga's custom chips are used to change some of the color palette in mid-screen. You have the option of changing anywhere between 1 and 15 colors in each slice. (A slice is a single line on a non-interlaced screen or two lines on an interlaced screen.) Slicing 15 colors is the old "SHAM" technique, which can have problems, depending on how much your display is overscanned and whether you are running in PAL. Slicing 7 colors should work properly in all display modes under all conditions on all machines. SEVEN COLORS IS THE MOST YOU CAN SLICE WHILE REMAINING COMPLETELY COMPATIBLE WITH ALL AMIGAS. Additionally, you can "freeze" a palette once it has been selected, so that it will be used for subsequent images, skipping the lengthy step of picking a new palette. You cannot freeze the palette of a sliced picture. Finally, you can load and save a palette. Loading a palette will also freeze it. Saving a palette is only possible when you're not using a sliced mode. Palettes are saved as IFF files that can be read by other programs, Dpaint IV, for example. Save Mode This controls how a "sliced" image is saved as an IFF file. PCHG will write a "multi-palette" file, a new standard, which was developed by Sebastiano Vigna, the author of Mostra, a shareware all-purpose IFF display program. Mostra versions 1.07 and later can display multi-palette files. SHAM writes a "SHAM" (Sliced HAM) file. Non-HAM files may be saved with this mode, but I doubt if anything will handle them correctly. "Dynamic" writes a "dynamic" file, with the information expected by a program like Dyna-Show or DynaMate. Again, any file may be saved with this mode, but only HAM and 4 bitplane hi-res are likely to be supported by other programs. You can check more than one save mode at a time. This will save the same information up to three different ways in the same IFF file. (Using three different IFF "chunks".) This lets you save a single picture with SHAM or dynamic information for older viewers and PCHG for modern viewers. Lock Background This option forces HAMLAB PLUS to use the background color of the original image as the background/border color of the output image. If this is unchecked, then HAMLAB PLUS will pick a palette without regard to the original background color, then use the closest match to the original background as the output background/border color. 24->12 Dither This selects the type of dithering used to reduce a 24-bit image to a 12-bit image. The following choices are available: None No dithering Floyd-Steinberg Serpentine error diffusion to 4 adjacent pixels Jarvis Serpentine error diffusion to 12 adjacent pixels Stucki Slightly different 12-pixel error diffusion Ordered Dispersed dot ordered dither Random Random dither Spiral-Dot Clustered dot ordered dither 12->Display Dither This selects the type of dithering used to reduce a 12-bit image to the small number of colors (2-64) actually used in the output. This has no effect on HAM images. The following choices are available: None No dithering Floyd-Steinberg Serpentine error diffusion to 4 adjacent pixels Jarvis Serpentine error diffusion to 12 adjacent pixels Stucki Slightly different 12-pixel error diffusion Why two different dithering controls? The reason has to do with the two step process HAMLAB PLUS uses to go from 24-bit data to something that the Amiga can display. (More details on this are in the following section.) These two steps are: 1) Reduce the picture to the Amiga's 4096-color (12-bit) palette 2) Reduce the picture to the number of colors that the Amiga can actually display at one time. Here's an example: Let's say we start with a 24-bit image that contains, among other things, 200 different intensities of pure blue. For the first step, we must reduce the number of blues to 15, because that's all we can represent with only 4 bits to control the blue. For the second step, we may only be able to display 16 colors for the entire image, and perhaps that leaves us with only 3 different blues in our final palette, so the second step must reduce the number of blues from 15 to 3. In both steps, dithering helps prevent "banding," which can happen when gradual color changes (like our original 200 blues) are represented with only a few (in this case, 15 or 3) colors. The two dithering steps can be controlled independently because dithering takes time, and sometimes one or both steps are unnecessary. For example, if you want to convert an Amiga HAM picture to hi-res, then 24->12 dithering is not necessary because the picture already has a 12-bit palette, but 12->display dithering may be very helpful because we're going from 4096 possible colors to only 16. One Step Dither Finally, there is one more option which changes the way HAMLAB PLUS dithers. Selecting the "One Step Dithering" control does two things: 1. It causes the 24->12 dither setting to be ignored 2. It uses the 12->display dithering method, but goes from 24-bit data direct to the display in one step. Dithering in one step is more accurate than doing it in two steps, since some information is lost by keeping only a 12-bit intermediate value for the two step process. However, one-step dithering means that the 24-bit data must be accessed more often, so it is probably not practical to use unless you are using a 24-bit cache. One-step dithering has no effect on HAM images. THE AREXX CONSOLE This window allows you to enter AREXX commands by name. You can enter a HamLab AREXX command, or the name of an AREXX macro. HamLab AREXX macros are stored in the REXX: directory and end with ".hl" Examples: CMD> message "hello there" (displays "hello there" in the message area) CMD> foobar (since there is no built-in foobar command, this attempts to run REXX:foobar.hl) See the command documentation for a complete list of AREXX commands and their syntax. AREXX FUNCTION KEYS HamLab Plus also allows you to execute AREXX macros using function keys when the main window is active. The F1 key will execute "F1.hl", F2 will execute "F2.hl", and so on. The Control, Alt, and Shift keys will modify the name of the command to be executed by adding a 'c', 'a' or 's' to the beginning of the file name, so Control-Alt-Shift-F10 will execute the macro named "casF10.hl" THE HAMLAB PLUS PIPELINE AND CACHES HAMLAB PLUS does all of its processing in a "pipeline" fashion, which means that all operations happen in a particular order, with the output of an earlier step serving as the input of the next step. HAMLAB PLUS also does all operations in a fixed order. While this loses some flexibility, it does avoid one major limitation: memory. HAMLAB PLUS can work on practically any size image, and, at a minimum, only needs to keep about one or two scan lines of that image in memory at one time. This does mean that some things have to be done twice. For normal processing, HAMLAB PLUS must first process the entire image to choose a palette, then make a second pass on the same image to convert it to that palette. This would mean that practically all of the steps in HAMLAB PLUS's process, from reading the original image, through all cropping, scaling, dithering, etc., would be done twice. HAMLAB PLUS does allow a way to avoid a lot of repitition, if you have either memory or disk space sufficient to hold an image. It does this by using two caches, which are temporary 12- and/or 24-bit images held at certain points in the pipeline, and saved either in memory or on disk. Using a cache means that after HAMLAB PLUS has selected a palette, it doesn't need to go all the way back to the original image to be able to display it. Instead, it need only go back to the 12-bit cache, which holds the image after much of the processing has already been done. If you use caches, they will stick around until you exit the program or use the Clear function, or until you change a setting which means that some processing upstream of the cache must be re-done. Here is the order in which HAMLAB PLUS does its operations (top to bottom). Where the caches fall in this order is also shown. reading original image from disk input cropping [24-bit cache] scaling color correction Here is where an exporter fits in -- it takes 24-bit data after scaling and color correction, and saves it in a file. reducing to a 12-bit image (possibly with dithering) [12-bit cache] palette color selection rendering to display or output file (possibly with dithering) From this pipeline, we can see that if we're using both 12-bit and 24-bit caches, then if we change the display mode (meaning we need to choose a new palette) then we only need to go back as far as the 12-bit cache to calculate a new palette. However, if we change the size of the picture, then we have to go back to the 24-bit cache, resize the picture, and build a new 12-bit cache.