P R I N T   S H O P   C L I P   A R T
BY PHILIP LAMB  DIGITAL DYNAMICS

Essential Information
=====================
This program is freeware. Use it, enjoy it, and send no money!!
You are asked to distribute it as widely as possible, providing you retain it intact with all necessary files, sourcecode and this documentation. You may not charge money for the sale of this program, only for the cost of the distribution medium.

Requires Apple IIe or //c, with ramdisk, any size, called /RAM
To begin using simply place all the files from the Shrinkit archive into one directory, then from Basic.System, run PS.CLIP.ART

Files included in this package
==============================
PS.CLIP.ART  This is the big cheese. It should be run from Basic.System to
             start PS Clip Art
PS.CLIP.ART.PIC  This is the Digital Dynamics intro screen
CLIP.ART.CODE  Machine language subroutines used in PS.CLIP.ART
MG.UNPACK, UPK.OBJ  Minigraphic unpackers used by PS.CLIP.ART
AUX.TYPE.SET  A couple of little machine language utilities
PS.CLIP.ART.DOC  You have to know how to run it
CLIP.ART.CODE.S, MG.UNPACK.S, UPK.OBJ.S, AUX.TYPE.SET.S, UNPACK.FAST.S
             The Merlin Pro sourcecode for the machine language programs
UNPACK.FAST  Fast single-size unpacker, included for use in your own programs

Introduction
============
While this program is called "Print Shop Clip Art", you certainly do not need Print Shop to run it! The great thing about this program is that it works with something that you can easily create: Hires pictures. (Double Hires screens can also be used. The program will read only the first half, thus some screens may look odd.) It allows you to clip 88x52 black and white mini-graphics from hires screens, assemble these graphics into clip art files, load these files into "The Print Shop" or "The New Print Shop" by Br0derBund Software and print them in cards, posters, calendars. Also included in the package, and most useful to those without Print Shop are three mini graphic drawing programs. These can be called from BASIC or assembly to display mini-graphics in 3 sizes anywhere on the hires screen. This is great for use in programs where you need a small-format graphic to appear.

The Minipix Format
==================
When the Print Shop first appeared, the only type of graphics it used were small 4 sector DOS3.3 files, called minipix. Because the range of them built into Print Shop was limited, people drew their own, using the print Shop Graphic Editor, and soon these little 88x52 pictures were everywhere. There were disks and disks, just packed with them. The storage format was quite simple, basically just a bit mapped image, with every 11 bytes of the file mapping to one line of 88 dots on the screen. An extra 4 filler bytes were tacked on the end of each mini-graphic file. Each file held only 1 mini-graphic. 52 lines x 8 bytes + 4 = 576 bytes.
     Now when "The New Print Shop" came along, you could convert these little graphics to the new format. It turns out that all that was done to each graphic to convert it, was a small header was placed at the start, and the 4 filler bytes were dropped from the end, and so 576 byte graphics became 605 byte "NPS" compatible graphics. (Other graphics formats exist for NPS but this converted 605 byte kind is all that PS.CLIP.ART can use)

PS.CLIP.ART works with both of these formats. The converted 605 byte mini-graphics are referred to as MINPICS, or as only one at a time can be handled, MINIPIC. This is kept in a buffer in memory referred to as the minpic buffer. Captures from the hires screen, redrawing onto the hires screen both use this buffer. The old 576 byte graphics are referred to as CLIP ART FILES because several of them can be assembled into a single file. A CLIP ART FILE with just one graphic in it can be loaded into the (old) Print Shop if it is converted to Dos3.3 using for example, Copy II Plus or Apple System utilities. Graphics can be moved to and from this file from the MINPIC BUFFER.

For techies, the minipic buffer starts at 38400 or $9600 in memory. The 572 bytes of graphic data start at 38433 ($9621). The clip art file grows downwards from 38400. There can be up to 24 mini-graphics in the file:

# GRAPHICS   LOAD @   FILE LENGTH    #     LOAD FILE @     FILE LENGTH
1     $93C0 (37824)   $240 (576)     13    $78C0 (30912)   $1D40 (7488)
2     $9180 (37248)   $480 (1152)    14    $7680 (30336)   $1F80 (8064)
3     $8F40 (36672)   $6C0 (1728)    15    $7440 (29760)   $21C0 (8640)
4     $8D00 (36096)   $900 (2304)    16    $7200 (29184)   $2400 (9126)
5     $8AC0 (35520)   $B40 (2880)    17    $6FC0 (28608)   $2640 (9792)
6     $8880 (34944)   $D80 (3456)    18    $6D80 (28032)   $2880 (10368)
7     $8640 (34368)   $FC0 (4032)    19    $6B40 (27456)   $2AC0 (10944)
8     $8400 (33792)   $1200 (4608)   20    $6900 (26880)   $2D00 (11520)
9     $81C0 (33216)   $1440 (5184)   21    $66C0 (26304)   $2F40 (12096)
10    $7F80 (32640)   $1680 (5760)   22    $6480 (25728)   $3180 (12672)
11    $7D40 (32064)   $18C0 (6336)   23    $6240 (25152)   $33C0 (13248)
12    $7B00 (31488)   $1B00 (6192)   24    $6000 (24576)   $3600 (13824)

The filler bytes of the first graphic in the file are utilised to record the number of graphics in the file,and the file load address:
$95FD (38397) Number of graphics in file
$94FE & $95FF (L,H)Load address of file

Program organisation
====================
The program is split into 4 distinct areas, each of which is accessed from the main menu.
     The "EDIT MENU" deals with editing of the hires screen, clipping of graphics, and drawing of graphics onto the hires screen. Initially, you are placed in the hires screen viewing mode. Press the spacebar for a screen displaying the keys that you can use.
     The "MINIPIC MENU" deals with the minipic buffer, including saving as a New Print Shop mini-graphic, loading a 605 byte converted mini-graphic, and viewing the buffers contents. All operations are listed on the menu.
     The "CLIP ART MENU" deals with the clip art file, including saving, loading, clearing specific graphics within it to black, adding a graphic stored in the minipic buffer to the file, moving a graphic in the file to the minipic
buffer, and viewing graphics in the minipic file. All operations are listed on the menu.
     The "HIRES MENU" deals with hires screen loading, saving and clearing to black. Note that to clear to white just clear to black and invert from the edit menu. The options are listed on the menu.

Note that most operations are menu driven. Pressing escape or control-A from a sub menu will return you to the main menu. If you have selected an option, but you do not wish to carry it out, usually, pressing return without entering any data will return you to the menu.

Typical operations
==================
Loading a screen, clipping a graphic, saving the graphic:
     Go to the [H]ires menu. Use [P] prefix change and [/] catalog if you wish to find the screen to load, then select [L]oad from the hires menu. Enter the filename and press return. Note that double hires files may be loaded, but as only the first half is read, the resulting hires creen may look slightly odd. Get back to the main menu and press [E] to get to the edit screen. To clip a graphic press [C]. A flashing capture box appears. Note that graphics can only be clipped at one scale. The arrows and keys W,A,S,Z move 10 pixels at a time. Keys I,J,K,M move 1 pixel at a time. To cancel capture mode press [escape] or to do the capture press [return]. Note that the captured graphic is placed in the minipic buffer, so any graphic in the buffer already will be wiped. When the graphic capture is completed the screen will flash. Press [Q] to return to the main menu. You can now select [M]inipic menu, to view the captured graphic. [T]oggle scale selects the viewing scale. The graphic will be centred in the screen. If the graphic capture is not satisfactory, you can go back to the edit screen and try again. If it is OK, and you wish to save it as a 605 byte, single graphic, NPS compatible file then choose the [S]ave option from the minipic menu. If you wish to add it to the clip art file, or save it as an Old Print Shop compatible graphic then follow the instructions below.

Creating a Clip-Art file, saving, loading:
     A clip art file may be created by moving a graphic from the minipic buffer, using the options under the [C]lip art menu. Graphics may also be moved to the minipic buffer from the clip art file.
To create a new clip art file, you should first have the graphic to be added in the minipic buffer. Then from the clip art menu select [M]ove, and following that [F]rom Minpic Buffer. If there are currently graphics in the minipic file you will be given the option of overwriting these. To just add to the end of the file, select [A] for append. You may have up to 24 graphics in a clip art file. The moving to and from the minipic file takes a minute, so be patient.
Individual graphics can be viewed in much the same way as for the buffer graphic. Simply set the viewing scale, and select [V]iew from the menu.
Graphics may be cleared by selecting [C] clear from the menu. Clearing the last graphic in a file will shrink the file by 1. To delete a graphic, and have those higher numbered move into its place is possible, but requires some work. You must move each graphic that follows the one to be deleted to the minipic buffer, and then move it from the minipic buffer to its new place in the file, overwriting the graphic below. This must be done for each graphic above the one to be deleted. Finally the last graphic in the file should be cleared.
When you are happy with the minipic file, selecting [S]save will allow you to save it to disk.
Clip art files can also be loaded from disk by pressing [L]. the program will automatically determine whereabouts in memory the file should reside, even if the file has never been loaded into PS.CLIP.ART before. If the file is not a multiple of 576 bytes long, it will not be loaded. Note that loading a clip art file destroys any already in memory, although the minipic buffer remains unchanged.

Edit Menu options
=================
As well as handling clipping of graphics from the hires screen, the edit screen allows some other functions as well. Graphics in the minipic buffer can be x-drawn to the screen in one of three sizes by pressing [X]. A flashing rectangle indicates the draw area. It is moved in the same way as the capyure rectangle. [esc] exits or [return] draws.
The hires screen may be mirrored horizontally by pressing [M] or flipped vertically by pressing [F] or inverted by pressing [I]. The machine language routines that carry out these functions reside in the file "CLIP.ART.CODE". The Merlin Pro source code is included if you wish to use these routines in your own programs.

Using graphics in your own programs
===================================
This ability is one of the most useful things about PS.CLIP.ART. Three different drawing programs are included in the package. They can be called from BASIC or assembly.

MG.UNPACK This routine unpacks a standard 88 x 52 mini graphic from a clip-art file created with PS.Clip.Art into the current hires drawing page.
     Load: into any free page of memory (relocatable) Length is $100
     Graphics: drawn from clip art file, located at appropriate mem. location
     Scales: draws at scale = 1, 2 or 3
     Entry: desired X,Y coordinates of the top left of the graphic should be stored in HORIZ ($E0 = 224) and VERT ($E2 = 226). The desired scale factor stored (1,2 or 3) stored in SCALE ($E7 = 231) or set with the Applesoft SCALE= command. To draw one pic by number either JSR LoadAdr with picnum in A, or CALL LoadAdr+2 or JSR LoadAdr+2 with picnum in 215 ($D7). To draw next picture in succession either CALL LoadAdr+52 or JSR LoadAdr+$34
     Execution time: Scale = 1 takes ~270 milliseconds, Scale=2 takes ~430 ms, Scale=3 takes ~610 ms.

UNPACK.FAST This routine operates in almost exactly the same manner as MG.UNPACK except the only acceptable value for scale=1. It does it fast, hence its name.
     Load: into any free page of memory (relocatable) Length is $9A
     Graphics: drawn from clip art file, located at appropriate mem. location
     Scales: draws only at scale = 1
     Entry: desired X,Y coordinates of the top left of the graphic should be stored in HORIZ ($E0 = 224) and VERT ($E2 = 226) and desired picnum should be stored in PICNUM ($D7=215). Entry is then JSR LoadAdr+6 or CALL LoadAdr+6 from BASIC. Alternately picnum can be passed in A with JSR LoadAdr+4 or picnum passed in A, and x,y, coords passed in X,Y with JSR LoadAdr. To draw the next graphic in the file use JSR LoadAdr+$27 or CALL LoadAdr+39
     Execution Time: ~143 milliseconds.

UPK.OBJ This routine unpacks 572 bytes of graphic data from a specified memory location, not a clip art file. Its opartion is almost the same as MG.UNPACK
     Load: loads at $300, length is $D0 bytes
     Graphics: Draws from 572 bytes of graphic data in memory. The memory locations of the graphic data are by default from $9621 to $9860, but different locations can be set by storing different values at the start of the program, the low byte at $301 (769) and the high byte at $305 (773).
     Scales: Draws at scale = 1, 2 or 3
     Entry: Store HORIZ, VERT, SCALE as for MG.UNPACK. The routine is called by CALL 768 from applesoft or JSR $300 from assembly.

For all the drawers, acceptable ranges for HORIZ and VERT are:
Scale = 1, Horiz = 0 to 192, Vert = 0 to 140
         2          0 to 104         0 to 88
         3          0 to 16          0 to 36

(The other program used by PS.CLIP.ART, AUX.TYPE.SET is called to set the auxiliary type of a 605 byte graphic so that NPS will recognise it. It also handles the determining of the load address of clip art files)

Use and enjoy!
==============
This is the first of several programs that I am releasing to the public domain. Keep an eye open for more Philip Lamb Digital Dynamics software. I hope you make use of this program, and I also encourage you to buy Broderbund Software's New Print Shop software. It is a great package, and a substantial improvement over the old one.