The Datafile PD-CD 3/PDCD_3.iso/utilities/utilsp/palgen/!PalGen/HelpGen/HelpText

Text File | 1995-03-08 | 12.8 KB | 351 lines

@#Reason
                  Documentation for !PalGen

                      By Ian Nichols


Purpose of this program:  Edit/Generate 256 colour palettes

  Machine compatibility:  Anything with RiscOS 3.1 or higher
                          Looks better on a RiscPC.

     @%Instructions#  <- Click on this button for instructions on how to use
            this help system.

Like many freeware programs, !PalGen was written partly as a programming
exercise and partly to do something the way that the programmer wants it to
be done rather than the way everyone else seems to do it.  In this case, the
task in question is the generation and editing of 256 colour palettes,
primarily for use with images created by !Fractal, but the palettes can also
be used with any RISC OS 256-colour sprite.  Though it was developed on an
ageing A310 with no more graphics enhancement than a VIDC enhancer, it is
intended to be used on a machine with VIDC20, which allows the 256 colours to
be selected from a 24-bit palette.  It has been tried on a RiscPC (someone
else's - I'm still saving!) and seems to work as expected.

!PalGen can also save and load 256 colour palettes in the form used by the PC
freeware program FractInt.

     @%RiscOS#     RiscOS palette format

     @%Fractint#     FractInt palette format

!PalGen has been written to be fully RISC OS compliant, and considering that
it is only my second Wimp program I am quite pleased with its behaviour.  It
supports both the file and RAM transfer protocols, although you do get some
strange error messages when saving palettes into sprites in !Paint. I am told
that this is almost certainly due to a bug in !Paint, but if there is someone
out there who can find a bug in !PalGen which is causing this, please could
they tell me!.



@#Use
Using !PalGen
-------------

The way in which !PalGen works is somewhat different from other palette
editors you may have seen.  Instead of setting colours individually or
setting groups of colours by interpolating between two endpoints, !PalGen
represents the whole palette as a set of 3 histograms; one for the red
intensities, one for the green and one for the blue.  These histograms can be
altered using the mouse or by means of 3 equations.

     @%MouseOps#     Mouse operations

     @%Equations#     Alter With Equations

Starting the application and opening the main window are all done in the
usual RISC OS way.  I have not set up a run action for palette files (type
&FED), so to load them you will have to drag their icons onto the !PalGen
icon bar icon or the main window if it is open.  The default 256 colour
palette is automatically loaded when the program starts (this is the same
on a RiscPC as on the older machines).



@#MouseOps
Clicking on the icon bar icon, or dragging a palette file onto it will open
the main window and the palette window. By default the main window will
display the histogram for red intensities.  You can view and edit the green
or blue intensities by clicking on the appropriate radio button. Please be
patient, it is interpreted BASIC after all.  Each column of the histogram
represents the intensity (0-255) of a logical colour (also 0-255).  As you
move the mouse pointer over the histogram, the logical colour number and
intensity corresponding to the mouse pointer position are displayed to the
right of the radio buttons.

Clicking with...

Select: Will set the intensity of the red, green or blue component of the
        logical colour corresponding to the pointer position.

Adjust: Will set the intensity of the red, green or blue component of the
        logical colour correspoding to the pointer position and interpolate
        all the colours between the current pointer position and the last
        pointer position where a mouse click took place.

Note that if you hold down the mouse button, both of these actions will
auto-repeat as fast as the program can keep up.  The palette display (if
open) will update immediately.



@#Menu
Clicking with Menu whilst over the main window will open a menu with the
following items:

@%Save#   Save            Opens a save box

@%Equations#   Equations       Opens the 'Alter with equations' dialogue box.

     Show Palette    Opens the palette display if it is closed.



@#Save
The Save Box
------------
The Save box is not quite the standard RISC OS item - it has two radio
buttons to select the type of file you wish to save the palette as (see later
for brief description of the two types.  The palette is saved in the usual
RISC OS way, i.e. you drag the file icon to a filer window (or the
appropriate window of whatever other application you want to save it into).



@#Equations
Alter With Equations
--------------------
The 'Alter With Equations' dialogue box contains 3 writable icons into which
you can type equations to alter the red, green and blue components of the
colours in the palette.  If you press RETURN or click on the 'Alter Palette'
icon, the program will execute a FOR...NEXT loop for each logical colour
(0-255), applying the expressions to the appropriate colour component.



@#EquationVars
There are 2 variables which you can use in the expressions you type: LCN% and
CV%.  LCN% is simply the logical colour number.  CV% is used to store the
current value of each colour component for each logical colour just before
the expression is evaluated, i.e. leaving the expression as 'CV%' (the
default) will not change that component of the palette.  CV%/2 will divide
the intensities of a colour component by 2 for the whole palette.
Intensities greater than 255 or less than 0 are checked for and clipped if
necessary.

By using this facility it is possible to do some rudimentary colour
processing.  Load a 256 colour sprite into !Paint and make sure it has its
own palette.  Save the palette into !PalGen and alter it, then save it back
into the sprite window in !Paint.

Some useful ones to try might be:

     255-CV% will invert a primary colour.  Using this for all 3
          primaries will produce a colour negative of the image.

     CV%+x or CV%*x will increase the amount of a primary (can be
          used to lighten/darken an image or create/correct a colour cast).

     CV%/x + y will compress the range of tones used in the image

     (CV%-x)*y will expand the mid-tones of the image to fill the full
          tonal range (if the image contained tones at the extremities,
          these will be clipped).

You can also use boolean expressions to limit the range of logical colours to
be altered.

     CV%+(50*-(LCN%>128 AND LCN%<192))

will add 50 to the logical colours from 129 to 191 (inclusive).

This works because a boolean expression such as (LCN%>128 AND LCN%<192) gives
a result of TRUE or FALSE; TRUE has a numerical value of -1 and FALSE has a
numerical value of 0.




File Types Supported
--------------------

Two file types are supported: the standard RISC OS 256 colour palette, as
exported by !Paint and as used by !Fractal, and the 256 colour palette files
used by the PC freeware program FractInt.


@#RiscOS
The RISC OS palette files contain a sequence of 6 bytes for each colour as
follows:

    19 <logical colour number> 16 <Red> <green> <blue>

This sequence corresponds to the BASIC command

           VDU  19,l,p,r,g,b

Which is used to set the physical colour of logical colour 'l'.  These files
are identified by having the file type &FED and being 1536 bytes long.  When
files of type &FED are loaded into !PalGen, the length of the file is checked
and the first 3 bytes are tested (they will always be 19 0 16 if all is
well).



@#Fractint
The files used by FractInt are plain ASCII text files and should have the
type &FFF (text) or &FE4 (DOS) before you try to import them.  When you
export this type of file, remember to give them the extension .MAP before you
try to load them into FractInt.  They consist of red, green and blue values
(separated by spaces) for each logical colour in order, starting with 0, one
line for each logical colour. They may also contain embedded comments on any
line, after the colour information.

Because they are constructed in this way, these files do not have a fixed
length, which makes them slightly trickier to deal with.  If you have
problems importing these, load them into your favourite text editor and
examine them, bearing in mind the following points.

1)   !PalGen checks that the first 3 bytes of the file give a valid
     number in the range 0-255.  It does this by reading successive
     bytes from the file until it finds a numeric character, then
     assembles successive bytes into a string until it encounters a
     non-numeric character.  If it has read more than four bytes
     (i.e. 3 digits plus the next, non-numeric, character) then it
     assumes that the file is not a valid palette file and reports
     an error.

2)   If the file contains any comments then they should be separated
     from the colour information by at least one TAB character
     (ASCII 9).  Note that any comments are ignored when !PalGen
     imports these files and that !PalGen adds comments of its own
     when exporting palettes in this format.




Well, I hope someone out there finds this program useful.  If anyone is
wondering why I have included some sort of  support for a PC program, the
answer is this: I believe that if Acorn machines and RISC OS are to survive
as a computing platform, it is important that we can exchange data with
users of other platforms in both directions.  Especially when those 'users of
other platforms' are also ourselves. Acorn users can import a variety of data
types from other platforms (mostly the IBM PC clones), but this is almost an
implicit admission that our platform is 'not good enough' - if it's any good,
why can't we create our own masterpieces? Well we can, its just that we can't
easily get them onto other types of computer....

I like to think that in some small way I am helping to spread the message of
data portability by doing this.



@#Status
!PalGen is freeware.  You can give it to whoever you like as long as you
include this file don't charge them any money (except for the disc).  The
author retains copyright of !PalGen.



@#Thanks
Finally, thanks to...
---------------------

Mike Curnow et al for producing !Fractal, which led me to want to write this
program in the first place, thereby forcing me to tackle the intricacies of
RISC OS compliance, and also for encouragement, feedback and bug reports.

The Stone Soup group for producing FractInt, (even though they did have to do
it on a PC clone) which, I believe, inspired !Fractal.

Ben Summers for writing HelpGen, which was used to produce this help system.

Whoever it was who designed the icon for filetype &FED (palette) which I have
included with this program (it is loaded by the IconSprites command in the
!Boot file).  Likewise the nice round radio buttons.

Dominic Symes for producing !Zap - the best text editor at the price (ha ha).

Dick Alstein for producing !TemplEd, which I used to generate my templates.



@#Author
Ian Nichols
128 Westbury Road
Westbury-on-Trym
Bristol
BS9 3AR

E-mail: [e-mail]

February 1995



@#Versions
Version History
---------------

1.00 December 1994

The first version which actually performed all the tasks that I wanted it to
(i.e. loading, editing and saving RISC OS and FractInt palettes).  Also the
first version to be released.


1.10 February 1995

A smartened up version with the following extra features:

     The application has a smart new icon.

     Histograms are displayed in the appropriate primary colour.

     Colour number and intensity information are blanked out when
     the mouse pointer leaves the histogram.

     FractInt palettes can be loaded with the DOS filetype (&FE4),
     so they can be loaded straight from DOS discs without changing
     their type to text (&FFF).

     Warnings are issued before quitting or loading new data if
     the current data has not been saved to permanent storage.

     Intensity values are now truncated properly when 'Alter With
     Equations' generates a value <0 or >255.



1.11 February 1995

     An asterisk is displayed after the file name in the title bars
     of the main window and palette window to indicate that the
     currently loaded palette has been altered.

     Last minute update: the above now works when the only changes
     are made using the 'Alter With Equations' feature.




@#Instructions
How to use this help system.
----------------------------

At various places in the help file, you will see little buttons like this:

                @%Instructions#

with some text next to them.  Click on the button to go to the subject
described by the text (as you may have done to get here).  Double-Click with
adjust anywhere in this window to return to the point you jumped from.

Alternatively, use the Menu button of your mouse to bring up a menu of
subjects which you can jump straight to.  If only all of life were this
simple!