show.xp

.lf=c
.tm=7
.sp=10
.hf0=n
S   H   O   W

Version 2.01

by:
Brian C. White

Copyright (c) 1989 by Softhouse Computing
.lf=j
.sp=20
Distribution notice:  This program is NOT public domain.  It is copyrighted by the author.  You can, however, download it, upload it, pass it around, (you can even use it) as long as it's FREE!


DISCLAIMER:  This program is NOT finished!  It has been uploaded in its current state for the benefit of those who are interested in this type of utility and to also promote the writing of the picture decoder modules.  The program and its support modules that accompanied this doc file have been tested fairly extensively and seem quite reliable (they haven't crashed).
.pg
.hf0=c,pn=1
.he1="S H O W"
.hl2=3,hf2=l
.he2="Brian C. White"
.hl3=3,hf3=r
.he3="Softhouse Computing"
.hl4=4,hf4=c
.he4="The Program"
"Show" was designed from the beginning to be a versatile method of displaying the various types of pictures formats that exist.  To accomplish this, the program is broken down into two parts:||Screen handling and Picture decode.  The main program is what does all of the work to create a graphics screen, allow direct memory access (via WInfo\xWInfo\ by Ron Lammardo) to that screen, and do any post-display processing on the picture.  The second part of the program is assigned to various "Decoder Modules"\xDecoder Modules\.  It is these that do the actual work of reading the disk file and creating a picture from it.

To allow these two parts to work together, a specific type of interface has been designed between them.  The main program is actually split into two separate parts, one that calles the decoder module, and one that does any screen work that the decoder module requests.  The first part is straight forward and, after setting up the graphics screen, memory, etc., simply links to the proper decoder module and jumps to it's entry address.  The second part was much more complex, as it became it's own miniature operating system.\xOperating System\

"Show" was also designed with speed in mind.  To accomplish this, everything was written in pure 6809 assembly code and then optimized for speed (as opposed to optimized for size).  The decoder modules were also made faster (and simpler) by allowing them to have direct access to the screen RAM\xDirect Screen Access\.  The utility WInfo\xWInfo\ included in this package is used to find the RAM blocks containing the screen which is then mapped into the program's address space.  The address of the screen is passed to the decoder modules for them to write to.  This method is faster than Get/Put buffers and it allows the user to see the picture as it is decoded.  In addition, the decoder module does not need to know exactly what it is writing to, so such things as background screens\xBackground Screens\ and pictures larger than one screen, otherwise known as "Full Size Pictures",\xFull Size Pictures\ can be loaded without having to make any adjustments to the decoder module itself.
.he4="How to Use it"
.pg
"Show" gets its list of pictures to display from the command line\xCommand Line\.  Each picture pathname\xPathnames\ must be followed by a three letter extension\xExtensions\ that tells the format the picture is stored in (eg. pic1.BIN, /DD/MY_PICS/pic2.VEF).  "Show" will then step through every picture in the list, display it, and then allow you to scroll though it (if the picture is larger than one screen).  Each pathname must be separated by one or more spaces on the command line.  A separate 8k memory block is reserved for the picture list, so there should be no problem with using the wildcard abilities of Shell+\xShell+\ to display a whole directory in one line.  "Show" also accepts several options\xOptions\ on it's command line.  These options must come before the pathnames of the pictures.  The syntax for the "Show" command line is:

.lf=c
Show  [-opts]  pathname.ext [...]
.lf=j

The options supported by "Show" allow a fair amount of flexibility as to how you want the picture(s) displayed on your screen.  The options (either in upper or lower case) must be prefaced by a hyphen (-) and followed by a space.  Options can be specified either in one group or separately.  The options and their descriptions follow.

.in=2
.ri=2
"-C"||Colorize\xColorize\:||Invoking this option will tell the decoder modules to change a black and white picture into one with assumed colors.  This is useful for displaying PMODE 3 or PMODE 4 with artifact colors.  (Note:  At the current time, the BIN decoder module does not support colorization.)  This option also allows pictures with 16 level grey scale\xGrey Scale\ to display better by using colors that are "close to grey" for intermediate values.

"-E"||Extra|Colors|Mode\xFlipped Screens\:||Enabling extra colors via this option will allow decoder module to make use of the screen flipping capabilities built in "Show".  To do this, all the module has to do is request more than one screen during the S$ScrnSz system call and then follow the quidelines for loading into that type of screen.  Upon returning, "Show" will automatically begin flipping screens to produce the desired effect.

"-F"||Full|Size|Picture\xFull Size Pictures\:||This option will tell the decoder module NOT to fit the picture onto a single screen.  Without this option, all pictures will automatically be cut, compressed, etc. so they can be displayed on one screen\xSingle Screen Pictures\.  With this option selected, the decoder modules are free to request a screen of any length.  Once the picture is loaded, you can scroll up and down through the picture by pressing the Up-Arrow\xArrow Keys\ and Down-Arrow keys.

"-P"||Don't|Make|Picture|Proportional\xProportional Pictures\:||The CoCo-3 screen resolution is not proportional to all screen formats (eg. MAC).  The decoder modules therefore adjust the picture so it always looks proportional on the screen.  This can involve skipping whole rows of picture data and/or compressing the rows horizontally.  You may want to use this option if you are having trouble reading text written on the picture, or if you are planning to make a hardcopy of the picture to the printer.  This option is best used in conjunction with the "-F" option.  Otherwise, the picture will still be compressed vertically in order to fit it on one screen.  (Note:  At the current time, only the MAC decoder module supports non-proportional pictures.)

"-Snn"||Slide|Show\xSlide Show\:||Including this option will tell "Show" not to wait for a key, but rather hold the current screen on display for a few seconds before automatically advancing to the next picture.  Pressing a key during the pause will also cause "Show" to advance.  The default delay is 5 seconds, but this can be changed by supplying a pause (in seconds) directly following the "-S".  (eg. "-S5", "-S15", and "-S" are all valid)

After displaying a picture, "Show" will beep to indicate that it is finished.  Pressing the Up-Arrow\xArrow Keys\ or Down-Arrow will scroll the picture up and down the screen if it was larger than one page.  Pressing "Q" will quit\xQuit\ the program immediately.  Any other key will advance to the next picture.  (During a slide show, no beep will sound and the arrow keys will not function)
.in=0
.ri=0
.he4="Error Handling"
.pg
If show receives an error in trying to display an picture\xErrors\, it doesn't abort.  Rather, it simply goes on to try the next picture in its list.  These errors can happen if it comes across a picture type that it can't find a decoder module for, or if the decoder module finds an error in the picture file.  The last error that occurred is returned when the program finishes.

Show determines which decoder module to call by looking at a three letter extension on the picture name.  (eg. "pic.bin" will use "ShowBIN")  "Show" first tries to "Link" the subroutine.  If that fails, it will try to "Load" it from the disk.  If that also fails, error 221 (Module not found) will be returned.  With this method, you can merge as many decoder modules in with the main program or in separate blocks as you can fit inside one 8k block.  The block containing "Show" must not exceed $1E00 bytes and the decoder modules' blocks must not be larger that $2000 bytes.

"Show" uses the public domain utility "WInfo"\xWInfo\ by Ron Lammardo to gain direct memory access to the screen\xDirect Screen Access\, so an error will also be returned if this module could not be linked/loaded.  It is recommended that this module be merged with the main program to minimize screen access time.
.he4="Writing Decoder Modules"
.pg
\xDecoder Modules\The major reason behind writing "Show" in two parts is so that it could be expanded easily to handle new picture definitions.  In fact, all that is needed to handle the new type is just a subroutine module named "ShowEXT" where "EXT" is the same as the three letter extension of the picture type you wish to decode.  "Show" will then automatically call the new decoder module when it encounters a picture of that type in its command line.

A decoder module is called with its registers set as follows:

.lf=l
.in=2
.ri=2
.di=+5
|A|=|Path number of the file to decode -- "Show" has already opened the file in the proper mode
.di
|B|=|Callcode -- This byte has its various bits set to indicate what the decoder module is supposed to do.
.di
|X|=|Screen Start Address
.di
|Y|=|Maximum number of lines on one full screen
.di
|U|=|User memory pointer -- For decoders own use (See ShowDefs::SubMemSz)
.di
DP|=|Most Significant Byte of User Memory Address -- Decoder can therefore do direct page addressing for more speed
.in=0
.ri=0
.lf=j

In addition to the 1k (currently) of user memory, there is about 1.5k of stack space (outside of user memory) that is available for use.

Upon exit from the module, set the carry bit of register CC if exiting due to an error and put the appropriate error code into register B.  A new error type has been defined (E$BadPic\xE$BadPic\) should the file passed not have valid picture data.

\xDecoder Modules\The "Callcode" defines what the decoder module is supposed to do.  The bits in it are defined as follows:  (these can be found in the "ShowDefs" file)

.in=2
.ri=2
.di=+11
FullSize|=|\xFull Size Pictures\Permission is given to make the picture larger than one screen.  If this is not set, the deocder module *MUST* fit the picture on one screen.
.di
NoProp|||=|\xProportional Pictures\Don't worry about making the picture proportional.  The user wants all of the picture loaded.
.di
AskOpts||=|\xUser Prompting\Permission is given to ask the user for any specific options that that the decoder module would otherwise decide for itself.  Do *NOT* use any OS-9 I/O system calls to do this.  Use *ONLY* the system calls provided by "Show".
.di
Colorize|=|\xColorize\Permission is granted to add color to black and white pictures.  The BIN decoder will eventually use this to create a color display for PMODE 3 and PMODE 4 with artifact colors.
.di
Enhanced|=|\xFlipped Screens\Permission is granted to use the flipped screens to gain an enhanced screen with additional colors.  Screens are flipped automatically by "Show" upon return.
.*.di
.*SaveScrn|=|\xSave Picture\The module is to take the current screen (using the appropriate system calls to get the full screen) and save it in its own format.  This is quite a complex thing for pictures types that don't match (eg. saving color VEF as a black & white MAC) and may eventually be changed to a call to a separate subroutine module or removed entirely.  None of the included decoders support saving.
.in=0
.ri=0

For more information on how to write decoder modules\xDecoder Modules\, look through the supplied source for the included decoders.  Each is implemented slightly differently because of specifics for its type, but many similarities can be found.  The "Show" system calls are described on the following pages and are called by a SWI3 followed by the appropriate command byte.  For example:

.lf=l
.in=6
  .
  .
  .
lda   <screens   Desired number of screens (for flipping)
ldb   <colors    Desired number of colors
ldx   <scrnxsiz  Desired horizontal screen size
ldy   <scrnysiz  Desired verticle screen size
swi3
fcb   S$ScrnSz   Set up the screens palette registers
lbcs  showexit
sta   <screens   Actual number of flipped screens
stb   <colors    Actual number of colors (plus pixels/byte)
stx   <scrnxsiz  Actual horizontal screen size
sty   <scrnysiz  Actual verticle screen size
stu   <scrnsize  Size of screen (in bytes)
  .
  .
  .
.in=0
.lf=j

\xMoreMem\One quite complex routine that is almost identical in all of the included decoder modules is the one to requests more memory from the "Show" main program.  Called "MoreMem," it relies on a longword that describes where in the total picture the current "Window" is.  Since show can support a picture of up to 2Meg in size (If you can find such a picture that doesn't exceed the CoCo-3's horizontal capabilities), the longword is used to hold an offset into the whole picture.  Some pretty extensive commenting was done on this routine (as promised), so it shouldn't be defficult to understand.  Basicall, you just call it when U (the current screen address pointer) goes outside of the screen range, and it should return with new memory and an updated register U (as well as updating "linehold").
.he4="System Calls"
.pg
.lf=l
.di=39
REQUEST SCREEN SIZE INFORMATION        Return information about the current screen or set up new screen
.in=0
SWI3  S$ScrnSz  113F 00
\xScreen Size Information\
\xS$ScrnSz\
Entry Conditions:

.in=3
A   = number of flipped screens (0 = return current value)
B   = number of colors for screen (0 = return current value)
X   = horizontal size in pixels (0 = return current value)
Y   = vertical size in rows (0 = return current value)
.in=0


Exit Conditions:

.in=3
A   = number of flipped screens
B   = number of pixels per byte (top 3 bits)
    = number of colors on the screen (bottom 5 bits)
X   = horizontal resolution in pixels
Y   = vertical size in rows
U   = size of available screen in bytes
.in=0


Error Output:

.in=3
B   = error code (if any)
CC  = carry set on error
.in=0
.lf=j


Additional Information:

.in=3
.di=+2
*|The Request Screen Size system call will take any information it is passed and try to create a screen of that type.  The routine will try to get the best fit considering what was asked for, but you can't be sure of what will be returned.  For example, a request for a 640x192x8 screen could get you a 320x200x16 screen.  You must check the returned values and handle them appropriately.

.di
*|The number of flipped screens (max 5) indicates how many screens will be flipped between during the actual showing.  No flipping will take place during the loading process.  A number of 1 indicates a normal screen like the original show used.  The number of screens that is requested is the number of screen that will be allocated.  Only an error will cause otherwise.  If an error is returned, the program should either exit or try a normal screen.

.di
*|The size of available screen is the amount of screen that was mapped into the current workspace.  When performing a load onto multiple screens, all screens have that size (returned in U) mapped in simutaneously.  (eg. 2 screens, each with 16k each, or up to 5 screens, each with 8k could all be mapped in at the same time.)  The screens sit ajacent to each other, so the second screen starts exactly U bytes after the start of the first screen, the third screen starts exactly U bytes after that, etc.

.di
*|Any registers set to zero will return their current values.  If all values were set to zero, no changes to the current screen will be made.  Otherwise, the neccessary screen type will be set and all screen memory will be zeroed before returning.

.in=0
Note:  This call has changed slightly since the original show (v1.01).  Any personal show decoder modules will need slight modification to handle the new use of the A and B registers.
.pg
.lf=l
.di=39
SET PALETTE REGISTERS                  Set the palette registers and border color for the current screen
.in=0
SWI3  S$SetPal  113F 01
\xPalette Registers\
\xS$SetPal\
Entry Conditions:

.in=3
B   = border color
X   = pointer to palette table
.in=0


Exit Conditions:

.in=3
none
.in=0


Error Output:

.in=3
none
.in=0


Additional Information:

.lf=j
.in=3
.di=+2
*|The Set Palette system call will set all the palette values\xPalette Values\ for the given screen, as well as the color for the border.  Each color is one byte long and is in the form --RGBRGB within the byte (standard OS-9).

.di
*|When doing flipped screens, the format is slightly different.  Register B is not used and the data pointed to by register X is extended.  The data is then 'n' sets of 16 bytes of palette data, where 'n' is the number of flipped screens.  Following this are 'n' more bytes of data that describe the border color.  See "ShowIMG" for an example of this.
.in=0
.pg
.lf=l
.di=39
SET OVERLAY WINDOW                     Create an overlay window for interactive communication with the user
.in=0
SWI3  S$SetOWn  113F 02
\xOverlay Windows\
\xS$SetOWn\
Entry Conditions:

.in=3
A   = width of window in characters
B   = height of window in characters
.in=0


Exit Conditions:

.in=3
none
.in=0


Error Output:

.in=3
B   = error code (if any)
CC  = carry set on error
.in=0


Additional Information:

.lf=j
.in=3
.di=+2
*|The Set Overlay Window system call will create an overlay window\xOverlay Windows\ over the current screen for interactive communication with the user.  The window created is A x B in size plus a double line border around it.  The text colors are Black on White (or the closest matching colors on the screen).

.di
*|Currently, the window is set up through OS-9 system calls, but this will not be guaranteed in future versions.

.di
*|To allow the window to be displayable regardless of the screen type, the maximum allowable values for the overlay window is 36x20.
.in=0
.pg
.lf=l
.di=39
OUTPUT TEXT                            Output a string of text onto an overlay window
.in=0
SWI3  S$OutTxt  113F 03
\xText Output\
\xS$OutTxt\
Entry Conditions:

.in=3
X   = pointer to text to output
Y   = number of characters to output
.in=0


Exit Conditions:

.in=3
Y   = number of characters written
.in=0


Error Output:

.in=3
B   = error code (if any)
CC  = carry set on error
.in=0


Additional Information:

.lf=j
.in=3
.di=+2
*|The Output Text system call writes to an opened overlay window\xOverlay Windows\ without processing or editing the data.

.di
*|This call functions identically to the OS-9 I$Write call except that the overlay window is automatically selected as the output device.
.in=0
.pg
.lf=l
.di=39
INPUT TEXT                             Read characters from the user via the keyboard
.in=0
SWI3  S$InTxt   113F 04
\xText Input\
\xS$InTxt\
Entry Conditions:

.in=3
B   = input attributes
X   = address in which to store the data
Y   = number of characters to read
.in=0


Exit Conditions:

.in=3
Y   = number of characters read
.in=0


Error Output:

.in=3
B   = error code (if any)
CC  = carry set on error
.in=0


Additional Information:

.lf=j
.in=3
.di=+2
*|The Input Text system call reads the specified number of characters from the user via the keyboard.  It returns the data exactly as read without additional processing or editing.

.di
*|The input attributes include "CursorOn" and "EchoOn" which will turn on the cursor and echo, respectively.

.di
*|This call functions identically to the OS-9 I$Read call except that the overlay window is automatically selected as the input device.
.in=0
.pg
.lf=l
.di=39
REQUEST ADDITIONAL GRAPHICS MEMORY     Gets more of the screen memory for pictures larger than one screen
.in=0
SWI3  S$ReqMem  113F 05
\xAdditional Graphics Memory\
\xS$ReqMem\
Entry Conditions:

.in=3
X   = absolute offset into picture (most significant word)
Y   = absolute offset into picture (least significant word)
.in=0


Exit Conditions:

.in=3
D   = size of new screen memory
X   = actual absolute offset into picture (msw)
Y   = actual absolute offset into picture (lsw)
U   = starting address of new screen memory
.in=0


Error Output:

.in=3
B   = error code (if any)
CC  = carry set on error
.in=0


Additional Information:

.lf=j
.in=3
.di=+2
*|The Request Additional Graphics Memory system call will remove the screen from your workspace and replace it with new memory (not necessarily at the same address or of the same size) for modification.

.di
*|The absolute offset\xAbsolute Picture Offset\ into the picture must be maintained by the decoder module (and initialized to zero).  "Show" will take this value and determine what memory to map in.  Upon return, these values have been modified to reflect the part of the picture memory that actually did get mapped into the address space.
.in=0
.pg
.lf=l
.di=39
REQUEST INFORMATION TABLE POINTER      Gets a pointer to a table of public information
.in=0
SWI3  S$ReqTbl  113F 05
\xTable Pointers\
\xS$ReqTbl\
Entry Conditions:

.in=3
A   = information table number
.in=0


Exit Conditions:

.in=3
A   = size of requested table
X   = starting address of table
.in=0


Error Output:

.in=3
B   = error code (if any)
CC  = carry set on error
.in=0


Additional Information:

.lf=j
.in=3
.di=+2
*|The Request Information Table Pointer system call will return a pointer to the table requested in register A.  The tables and their corosponding numbers are listed in "ShowDefs".  Currently, they are:

.in=+2
.di=+11
T.GryScl|-|These are the palette values that can be used to make a 16 level grey scale.  It makes use of colors that are "close to grey" for the effect.
.di
T.Compos|-|This is a conversion table for converting composite palette values to similar colors for display under RGB.  It should be used as a look-up table.
.di
T.FlipC2|-|This are color values that can be used when having a color displayed over two flipped screens.  The high and low nybles are different and each contains the intensity for one of the two screens.  Each nyble returns a value from 0 to 3.  By using these intensities, a total of 1000 colors can be created over three screens, with each color being displayed on two of the three screens.

.in=3
.di=+2
*|Note:  Under no circumstances should you write to these data tables!
.in=0
.he4="Future Additions"
.pg
\xFuture Additions\As I mentioned on the first page, this program isn't finished yet.  Here are some of the future additions I have planned:

.in=2
.ri=2
.di=+2
-|Fix my decoder modules so they follow all the rules defined in this doc.
.di
-|Printout support.  I can only do the SG-10 and compatible.  Anybody else wanna work on some others?
.di
-|An animation system call that will specify such things as palette cycling, etc.  Anybody got any suggestions here?
.di
-|GIF picture decoder module.
.di
-|Other decoder modules that I have specs for.  Everybody is welcome to write them, that's why I chose the "separate module" design.
.di
-|Control file support.  Contains file names, their display time, etc.
.di
-|Read picture pathnames from standard input
.di
-|More interesting slide show effects.  eg. sections appear in random order; fade out, then back in.  slide off the top/bottom/sides.
.di
-|Wild card pathnames because Shell+ has only a 2k parm area while "Show" can handle 8k.
.di
-|Random display order of named pictures.

.di
-|Ideas from other people
.in=0
.ri=0


Well, that covers just about everything.  This program is distributed as ShareWare to be my contribution to the pool of fantastic software that others have provided at the same price.  Thanx guys, I don't know what I'd have done without you.  Of course, donations are always accepted (I occasionally like to eat <grin>), but not necessary.  Your suggestions, comments, and gripes are always welcome.


I can be reached as:                  Brian White
                                      P.O. Box 1565
                                      Esterhazy, Sask.
                                      S0A 0X0  Canada

or on Delphi as:                      BRIANWHITE
.pg
.he4="Index"
.lf=l
.in=0,di=2
.* Merge "show.ndx" after this line.  Modifications will be needed.