Canvas 
version 1.1
Copyright (c) 1998


Author
Samuel Igwe



Introduction:
Canvas is a sprite image creator and editor I developed for my own personal
use. The need arose when I could not find a program that combined together
three of the most useful game programming tools, a .pcx viewer,palette editor
and most importantly a simple sprite editor in a DOS environment using a
standard vga card. In desperation I decided to write my own. 

Canvas can view and clip up to four images from a 256 color .pcx file and
import the clipped image to the sprite editor, where the user may easily
manipulate the sprite. The image size can vary between a minimum size of 8*8
to 126*126.A sprite grid serves as a window into the 126 * 126 maximum sized
sprite. Four screens display the contents of all four possible sprite buffers

The sprite editor may easily be used to create sprites for a game
program, and with the option of loading in a .pal file, all sprites may share
a common game palette. The palette editor allows the user the option of
loading,saving,creating or editing a game palette of 256 colors (VGA).

Canvas uses color 0 and color 255 for its menu and display routines. As such
these two colors maybe used but may not be changed in the palette editor.
FOR FAST EXECUTION RUN FROM DOS.



2. ACKNOWLEDGMENTS
******************
At this moment, I wish to thank Borland International for providing a powerful
and versatile assembler. This entire program (canvas and related video
subroutines) were written using Borlands Turbo Assembler version 2.1. I highly
recommend using Borlands powerful programming tools.



3. REQUIREMENTS
***************
100% IBM or compatible computer with a 80286+ processor
a standard VGA graphics card 
a minimum of 200k hard disk or floppy space
a Microsoft or compatible mouse with driver (OPTIONAL--NOT A REQUIREMENT)
200kb system ram (canvas uses 192k)
Ms-Dos (or PC-Dos) 3.1 (or higher)



4. STARTING CANVAS
******************
In the intro press F1 or click both mouse buttons to invoke the menu system.
Select "MODE" and choose among the three modes (PCX VIEWER,PAL EDITOR,SPRITE
EDITOR).The command menu maybe called up at any time by pressing F1 or
double clicking with BOTH mouse buttons(IF MOUSE/DRIVER IS INSTALLED).




4.1.THE PROGRAM COMMAND MENU
From this menu, the user may begin a new instance of any of the subprograms
(.pcx viewer,palette editor or sprite editor), or select a subprogram function
such as clip image, or set buffer.

note:the command menu may only be invoked from within one of the three
     subprograms and not from within a function (clip image,set buffer,load 
     data,save data,info).



     [THE PCX VIEWER]

     From within the command menu select .pcx and the current directory
     is displayed along with any pcx files within. Select pcx file to
     display by double clicking on filename or using up and down cursor keys
     as well as the enter key.
 

     clipping an image
     -----------------
     Once image is displayed the user may clip a portion of it by selecting
     the "clip image" function from the "operations" submenu of the program
     command menu. With the mouse, the user must click on a location with the
     left mouse button then define this location (by moving to the right and
     downwards). This should display a rectangular box around the image.
     Releasing the left mouse button causes the image defined by the box to
     be saved to the current buffer. The area must exceed 8 *8 in order to
     be saved.

     To save to another buffer, invoke the command menu and select "set buffer"
     underneath the "operations" submenu. There are any one of four buffers
     (numbered 0 - 3) that the user can use.

     To view the contents of any of the four buffers, invoke the command menu.
     Select "view buffer" underneath the "operations" submenu. The "TAB" key
     flips through all four buffers.
          
     
     saving/editing clipped image
     ----------------------------
     After the image has been clipped from the screen, invoke the command
     menu and select the sprite editor. Once in the sprite editor, invoke the
     command menu and select "set buffer" from the "operations submenu". From
     this choose any one of the four buffers and its contents will be displayed
     on screen. From within the sprite editor, edit the image and then select
     "save as" from the command menus "file" submenu to save image.



     
     [THE PALETTE EDITOR]

     The Palette Editor allows the user to edit 254 of the 256 colors      
     available for the current VGA mode (13h). Only color values 1-254 maybe
     edited, this decision was made based on the fact that canvas uses color
     values 0 and 255 to display command menu and screen prompts.

     
     screen display
     --------------
     The main screen presents the user with the RGB color bars as well as the
     256 color palette on the bottom of the screen as a set of color boxes.

     On the right is displayed an 8 * 4 block of the current color being
     edited. Page up and Page down will select any one of the color values
     between 1 and 255. 
     On the left, the red,green and blue attributes of the current color is
     shown along with a color bar indicator of the respective atttribute. 
     

     editing color attributes
     ------------------------
     keys: up,down,left,right,page up,page down,mouse left and right buttons,
           F2 and F3

     cursor keys:    The right and left cursor keys select among the 3
                     attributes (RGB), while up and down cursor keys increment
                     /decrement the particular color attribute.
                     Optionally, the mouse may be used. The color attributes
                     maybe incremented/decremented by clicking on the left and
                     right mouse buttons. Note that this affects the currently
                     highlited attribute (R,G or B)


     F2:             Allows the user to change the color being edited. the
                     user can cycle through all 254 available colors. Pressing
                     enter selects the currently highlited color box.                   To change the current color

                     The mouse left button can be used to select a new color to
                     edit by clicking on any of the colored boxes at bottom of
                     the screen.

 
     F3:             Creates a gray palette and sets the palette accordingly.


     saving and loading palette files
     --------------------------------
     The current palette (consisting of 768 attribute values (256 *3)) maybe
     saved to disk by invoking the command menu and the "save as" option from
     the "file" submenu. The user is prompted for a file name and the data is
     saved to disk.

     A 768 byte palette file (.pal) maybe loaded and initialized by selecting
     the ".pal" option from within "file" submenu. Once loaded the VGA palette
     is changed immediately (with the exception of color 0 and 255)
                     



     [THE SPRITE EDITOR]

     The Sprite Editor is enormously versatile as it allows the user to load 
     in a palette as well as creating and editing a sprite image. Loading in
     a palette allows all game sprites to utilize the same color palette. 

      
     screen display
     -----------------
     Initially the user is presented with a blank 42 * 42 sprite grid and
     sprite window (upper right corner). To the right of the screen is the 
     current color and value and above that is the 4 sprite windows represent
     ing the contents of the four buffers. Select "set buffer" from the
     operations submenu to initialize the screen to the contents of any of
     the buffers. "view buffer" will allow one to view any of the buffers as
     a 126 * 126 sized sprite.


     creating/editing sprite images
     ------------------------------
     keys:up,down,left,right,alt,ctrl,F2,F3,F4,F5,mouse left and right button

     cursor keys:    The up,down,left and right cursor keys allows the high
                     lighted marker to move within the sprite grid. The ALT and
                     CTRL keys (or mouse left/right button) places the current
                     foreground or background color at highlighted location.
                     the inner color box is foreground
                     the outer color box is background


     F2/F3:          Allows the user to change the color being edited. the
                     user can cycle through all 254 available colors. Pressing
                     enter selects the currently highlited color box.                   To change the current color

                     The mouse left button can be used to select a foreground  
                     color to edit by clicking on any of the colored boxes at
                     bottom of the screen.
                     F2== select new foreground color 
                     F3== select new background color


     F4:             Allows the user to set the foreground color to the color
                     currently being highlited by the marker on sprite grid.
                     This is the equivalent of dabbing a paintbrush on a
                     canvas.


     F5              Allows the user to switch every occurrance of a color with
                     another.
                     Use the highlite marker (cursor keys) to select the color
                     whose every occurrance you wish to change. Then using the
                     mouse or F2, select the the new color. Pressing F5 will
                     change every occurrance of that particular color to the
                     new user foreground color.

    
     loading a palette/sprite file
     -----------------------------
     Invoking command menu and selecting the "file" option presents the
     user with the choice of either a .pal (palette) file or a .sdf (sprite
     data file) file. Once selected the user may then choose the appropriate
     filename to load into the sprite editor.

     The "save as" option within the "file" submenu prompts the user for a
     filename. The extension .sdf (sprite data file) is appended to the
     filename string saved to disk.

     
     moving an image within the grid
     --------------------------------
     A sprite image can be moved left,right,up,down by the moving
     the marker box past the outer edge of the grid. This allows the user to
     pan through the image. The sprite grid servers as a window into the
     Sprite buffer. 

                    
     resizing the grid screen
     ------------------------
     Invoking the "resize grid" function from within the "operations" submenu
     allows the user to change the col and row length of the current sprite
     grid. Note that the currently displayed image (if any) is adjusted
     appropriately.
     The minimum grid size is 8 * 8 whereas the maximum is 42 * 42. One may
     save and edit sprites in a minimum of 8 * 8 and a maximum of 126 * 126




     [EXIT]

     When done with the program invoke the command menu and select this
     option, to end program run. Note that the program does not prompt you to
     save any data not previously saved as this is your sole responsibility.





5. CANVAS SubProgram functions
******************************
     
     Clear Screen
     Clear screen performs a different function depending on whether or not
     you are in pcx mode or you are in sprite mode. In the pcx mode the screen
     is just cleared. In the sprite mode, the current buffer and sprite grid
     screen are cleared.

     
     Clip Image
     Clip image is invoked from the "operations" submenu only from within the
     pcx viewer mode. It allows the user to clip an image from the current
     screen display. A mouse is required in order to use this function. Click
     and hold the left mouse button on the location where you wish to define
     the clip image box. While holding the left mouse button drag the mouse
     to the right and down to define the region you wish clipped.

     It is possible to clip four sprites, this is done by clicking on "set
     buffer" from within the "operations" submenu. Simply select the next
     buffer where you wish to store the next clipped image. You can invoke
     "view buffer" from within the "operations" submenu to view the contents
     of all four buffers.
     

     Rotate Image
     This subroutine rotates the image (at the current buffer being edited) by
     90 degrees to the right. Note that four rotations will bring the image
     back to its original position.


     Set Buffer
     This subroutine allows the user to select from one of four sprite buffers.
     Once the selection is made, the screen is updated appropriately. The image
     is also displayed on one of the four sprite windows to the right of the
     screen.
     PRESS ENTER TO SELECT, ESC TO QUIT.

      
     View Buffer
     This subroutine allows the user to view any one of the sprite buffers as
     a full 126 * 126 image. Press the TAB key to cycle through all four
     buffers. The cursor keys will allow the user to reposition the sprite image
     anywhere in the buffer.
     PRESS ESC WHEN DONE.


     Resize Grid
     This function is called only from within the sprite editor, and allows 
     the user to resize the current grids dimensions. The size change is
     displayed to the right of the sprite window. The final size is the size 
     of the current grid.

     The cursor keys allows one to resize the sprite grid. The minimum value
     is 8 * 8 and the maximum is 42 * 42. 

     Note that the current sprite image is adjusted once enter is pressed.
     The grid then serves as a window into the sprite buffer.
     PRESS ENTER WHEN DONE.

                 
     .Pcx
     Allows the user to select from any pcx file on the current directory.
     Upon selection, the program displays the selected pcx file.
     PCX VIEWER MODE.

     
     .Pal
     Allows the user to select from any pal file on the current directory.
     Upon selection, the program sets the palette to the contents of the
     selected pal file.
     PALETTE AND SPRITE MODE.

     
     .Sdf
     Allows the user to select from any sdf file on the current directory.
     Upon selection, the program sets the screen to the selected sdf files
     contents.
     SPRITE MODE.

     
     Save As
     In the palette mode, the program prompts the user for a filename, once
     read, the program determines whether the filename exists on disk. If it
     does, the user is prompted to allow overwrite. If it doesnt, the program
     saves the palette to the file. Maximum filestring is eight chars. The
     string .pal is appended to the filename string.

     In the sprite mode, the program prompts the user for a filename, once
     read, the program determines whether the filename exists on disk. If it
     does, the user is prompted to allow overwrite. If it doesnt, the program
     displays a window which allows the user to specify the col and row length
     of the image to be saved. Once selection has been made the program saves
     the .sdf file and the .sdf file as a compiled sprite with source.

     The .cs file format is useful to C,C++,Pascal and assembly language
     programmers.
     THE SPRITES COLOR VALUES ARE CONVERTED TO ASCII CHARS AND SAVED TO A
     TEXT FILE WITH THE EXTENSION .CS. THIS IS FOR GAME PROGRAMMERS WHO
     PREFER TO INCLUDE THE SPRITE IMAGE INTO THEIR EXECUTABLE AT ASSEMBLYTIME.
     IT CREATES AN ARRAY DECLARATION FOR CUTTING AND PASTING INTO SOURCE CODE.
     THE .CS FILE FORMAT WILL ONLY SAVE FOR A MAXIMUM OF 64 *64


     Info
     This just displays a small picture of the Author (thats me!!!) along with
     the name of the program and version number.




6.  QUESTIONS
*************

a.      Why did you write this program??
ans     I wrote this program when i realized that I needed a fast and versatile
        Method of clipping images from a graphics file (.pcx) created for
        games. With canvas I expanded on this to include among other things,
        a pcx viewer and a palette editor so that my sprites (game images)
        can utilize one video palette.

        But in truth canvas is a simple sprite editor, allowing the user to
        edit and manage up to four sprites at any given time. However canvas
        does not contain circle and rectangle drawing primitives as this is
        not a graphics editor.


b.      What does the extensions stand for?
ans     .pcx --- a very popular file format developed by ZSoft corp. See a
                 manual for file format.
        .pal --- a 768 byte file containing the contents of the palette regs.
        .sdf --- MY own sprite format. Acronym stands for Sprite Data File
                 the format is as follows.
                 byte 0=col length
                 byte 1=row length
                 remainder bytes =data
        .cs  --- MY own compiled sprite format. In short the contents of the
                 .sdf file above is converted (each byte) to its ascii
                 equivalent then saved to a text file and the extension .cs
                 appended.


c.      Why do I keep getting the message, "Set The Mode First"?
ans     In order to execute certain subroutines, the user must be in a certain
        mode. For instance, in order to execute "clip image" from the
        "operations submenu", the user must be in pcx viewer mode.


d.      Any other things we should know about before using canvas?
ans     Canvas is written in assembly language and optimized for the 80286
        and above microprocessors. Its best run in pure dos or at least
        in Msdos mode.
        The sprite editor "remembers" the names of the files loaded or saved
        and can simply prompt the user (after selecting save as) to overwrite
        that current file

        A mouse is needed for certain function such as for example the clip
        image subroutine.

        A sprite image can be moved left,right,up,down by the moving
        the marker box past the outer edge of the grid. This allows the user
        to "pan" through the image.
        THE SPRITE GRID SERVES AS A WINDOW INTO THE SPRITE BUFFER.

        
d.      What do I do if I discover an error?
ans     Although I would like to say that I have totally tested out canvas,
        There may (likely may not be) an error or bug lying in hiding. Please
        familiarize yourself with the program before reporting an error. Make
        sure the what you may consider an error was not indeed "a feature" of
        canvas. In all cases write down the error and details along with
        your system specs and send them (email preferably) to the address
        below.


e.      What is the current status of canvas?
ans     Canvas is freeware. It will likely remain so. I would however apprec
        iate a letter or email regarding the program. In short let me know
        what you think and what uses you have put this program through.

        Feel free to send me any hardware or software you have as part of a
        registration. Any thing will further my knowledge.


 snail mail address:
 SAMUEL IGWE
 20 WEST MOSHOLU PARKWAY SOUTH 
 BRONX, NY 10468

 email address:
 SAMIGWE@worldnet.att.net


 the zip file canvas.zip should include the following files
      canvas.exe                ;main executable
      canvas.prg                ;needed by canvas
      canvas.txt                ;this file

      mysha.pcx                 ;sample .pcx file
      raptor.pcx                ;sample .pcx file
             
      myship.sdf                ;sample sprite file
      world.sdf                 ;sample sprite file
      starship.sdf              ;sample sprite file

      canvas.pal                ;sample palette file




7. STANDARD DISCLAIMER
**********************

  By using this program you agree not to hold me responsible for any damages   
  to your system,and or peripherals. 

  Do not make any changes or modifications nor attempt to disassemble this    
  program. All rights reserved.

  All trademarks and names are the property of their respective owners.      


8. CONCLUSION
*************
  In the event to a bug,please feel free to contact me at the following
  email address or at my home address listed above. Also contact me if you
  have any new ideas as to how i can change/improve canvas. I may or may not
  consider it in a future version.

  SAMIGWE@worldnet.att.net
                      ENJOY CANVAS!!!  


;progression of canvas
;---------------------
june 29,1997            ;ver 0.9b initial release
july 17,1997            ;ver 1.0
                        ;corrected disk error handler
                        ;removed shareware registration annoyance
                        ;simplified intro interface
july 30,1997            ;corrected source save error
                        ;implemented function F3 (switch color)
december 12,1997        ;began rewrite of canvas now ver 1.1
                        ;redesigned interface
                        ;created event driven mouse interface
                        ;implemented ability to save and recall filenames
                        ;improved clip image to use mouse
                        ;increased the maximum size of sprite to be edited
                        ;to 126*126
                        ;improved user prompt and error messages.
                        ;removed color/palette mangling
                        ;optimized 256 color vga asm routines
january 23,1198         ;completed rewrite of version 1.1
     

     
