Tools en Utilities

home *** CD-ROM | disk | FTP | other *** search

/ Tools en Utilities / CDASS_5.ISO / shell / file / docmkr33.arj / SAVEPCX.DOC < prev

Wrap

Text File | 1992-11-27 | 24.5 KB | 475 lines

----------------------------------------------------------- -- -- -- Save PCX Version 1.00 -- -- -- -- (C) Copyright 1992, Prometheus Systems Incorporated -- -- -- -- Save PCX User's manual -- -- -- ----------------------------------------------------------- Introduction. ------------- SavePCX is a very small (less than 3Kb resident) which allows you to capture images from the graphics screen, and save them as PCX type pictures. Status. ------- SavePCX is Freeware. It is completely free... however, SavePCX is still copyrighted and you are not allowed to make any changes to the program or the documentation. You are allowed to distribute this program, but you are not allowed to sell it, you have to GIVE the copy away, you may not regain any losses made by distributing this program. Also, SavePCX may NOT be combined in a package of any sorts unless the package is COMPLETELY free. If you give a copy to a friend make sure he gets this documentation too. Installation. ------------- Since SavePCX is very small in size, this utility should not cause any problems, even in systems with little memory. Just type SavePCX at the DOS prompt to load SavePCX in memory. No parameters are needed. To load SavePCX in the UMB, type LH SavePCX or LOADHIGH SavePCX Be sure you have an UMB manager loaded (EMM386.EXE, QEMM.SYS, QRAM.SYS...). If you try to install a second copy of SavePCX, a message (Already in memory) will appear on screen and the second copy will not be installed. How it works ------------ SavePCX is a resident screen-capture utility. Once loaded, it will remain in memory and can be activated by pressing the "Hot Key" (Ctrl+Alt+S). Once activated, SavePCX will check the video mode and save the graphics screen into the current directory. The file is placed in the current drive and path. If there is no more room for the file the program will do it's best to close the file and return you to your task. Every file made by this utility can be recognized by the name PSInnnn.PCX where 'nnnn' represents a number from 0000 to 9999. An existing file cannot be overwritten by this utility, it first checks the filename, if the name already exists it increments the number and checks again until the filename doesn't exist. Operations. ----------- The operation of SavePCX is easy and can be done in a few simple steps. First load SavePCX in memory. Once loaded, a message that SavePCX is now resident or was already resident will appear on screen and you will be returned to the DOS prompt. Except for a small reduction in system memory (3Kb), you may continue using your computer normally. Second, now that SavePCX is an extension of DOS, it may be activated while in any program. The way for doing this is as follows: Hot Key: This combination of keys is used to activate the program. To avoid interfering with the current program, the keyboard will respond normally until these keys are pressed. Once the hot key is pressed, the current operation is suspended and the screen is saved on disk (current drive and directory). The hot key for SavePCX is Ctrl+Alt+S. What is saved. -------------- SavePCX will do it's best to identify the active video mode and save what you see on screen. Following video modes are supported. Mode 04h : CGA 320*200, 4 colour. Although this CGA mode can make use of any of four different colour schemes, due to the limitations of the PCX format version 3.0, the correct colour scheme will not be saved. This will usually not be a problem since most drawing packages only use the Cyan/Magenta/White (CMW) colour scheme. Mode 05h : CGA 320*200, 4 gray scale. This video mode is technically the same as mode 04h. Again due to limitations in the PCX format version 3.0, the gray scales are not saved. The picture is saved just like it was mode 04h Mode 06h : CGA 640*200, Monochrome. Again, Although it's possible to set the colour of the pixels, this colour is not saved. Mode 07h : Hercules 720*348 monochrome. This is really an odd one out. Since there is no sure way to tell if the Hercules card is in graphics mode, (there IS a technique to see if a TRUE Hercules is in graphics mode, testing has shown that this technique does not work for most hercules clones). SavePCX always assumes graphics mode is active when the hot key is pressed. If, at the time the hot key is pressed, alfanumeric (text) mode is active, the picture will be saved, but it will probably hold nothing but garbage. Mode 0Dh : EGA 320*200, 16 colour. Mode 0Eh : EGA 640*200, 16 colour. Mode 0Fh : EGA 640*350, Monochrome. Mode 10h : EGA 640*350, 16 colour. Mode 11h : VGA 640*480, Monochrome. Mode 12h : VGA 640*480, 16 colour. In all modes from 0Dh through 12H, there's a difference when you have an EGA or VGA card installed. If you have an EGA card, the picture will be saved with standard palette, Page 0. This is due to the fact that it's not possible to read out the EGA registers. If you have a VGA card, SavePCX will correctly save the active page, correct palette colours and in the case the screen dimensions have been changed, save the entire video buffer (It's possible to change the dimensions of the video buffer but still keeping the same screen size). Mode 13h : VGA 320*200 256 colour. Tweaked : Also called Mode-X, 13h/4, VGAX, Unchained VGA... This is a very nifty (undocumented) VGA mode, it's a mode that allows 256 colours but offers you multiple screen pages (unlike mode 13h). This mode is used by some games (Ultima Underworld (Origin), Red Baron (Dynamix)...) and lots of demos (Cronologia (Cascada), Vectordemo (UltraForce), Unreal (Future Crew)...). It's a hell to program in this mode but the gains can be enormous. You can fill the screen up to 4 times as fast as compared to mode 13h. SavePCX is probably the ONLY screen capture program around which saves screens in this mode. Problem is most games/demo's tend to take complete control of the keyboard and thus render SavePCX useless in that case. Nonetheless it's here. Warning. -------- To avoid disk drive errors, activation of SavePCX during disk operations is not recommended (because SavePCX uses the disk also). Under normal circumstances, pressing the Hot Key while you are reading/writing files, shouldn't cause any problems, SavePCXC will wait until DOS has finished reading/writing. If you are using a program which reads/writes the disk directly (Like Disk Optimizers (PCTools Compress, Norton Speeddisk,...)), it's best to reboot first, to avoid wrecking your harddisk by pressing the Hot Key. To avoid a problems with TSR-utilities (not only SavePCX). 1° : Do not load any TSR programs when in a DOS Shell. This will result in memory fragmentation ("memory allocation error") when quitting the program you invoked the DOS shell from. If no error occurs when quitting the program you invoked the shell from, you will loose a considerable amount of memory because the program is terminated but is not removed from memory. 2° : Most programs which have a shell built-in, release all unused memory. When trying to return to the program you shelled from, the computer will hang because the program can not re-allocate it's freed memory. 3° : Try not to run a program which uses the same combination of keys as the TSR does. About the PCX File format. -------------------------- This paragraph is only for those who are looking to incorporate pictures in their own programs or want to learn about the structure of PCX files. If you aren't one of these, just skip this section. This section requires you to know how to program the video hardware, because only the PCX format is discussed here. First of all I'd like to mention that there are a lot of descriptions of the PCX format around, but none of them (even the one by ZSoft) is correct on all counts. The format description here will probably be the easiest guide around and is based on a lot of tests done on PCX files created by various programs. The PCX-pictures created by SavePCX conform to the ZSoft specification. Some of the special cases which do not conform to the ZSoft specification are marked with an asterix (*), it's up to you to decide to incorporate the exception in your loader. If you need a PCX write routine, stick to the PCX convention for maximum compatibility. the PCX format supports several types of images, monochrome, 16 colour, 256 colour (8 bit) and even true 24 Bit colour. Altough these are the standard (PC) formats, you may have to accomodate for even more types when you want to write a general purpose PCX loading/writing routine, images from the amiga have a few more possibilities (8,32 and 64 colour, 16 colour Bitpacked...). Most probably however you'll need a PCX routine which correctly reads one specific type of file. The PCX file begins with a 128 byte header. Usually you can ignore the header, since your images will probably all have the same resolution and number of colours. If you want to process different resolutions or colours, you will need to interpret the header correctly. The remainder of the file consists of encoded graphic data. The encoding method is a simple byte oriented run-length technique. The header (All Bytes are unsigned, Words are signed) : Offset Item Type Description comment. ------ ------------ -------- ----------------------------------- 0 Manufacturer Byte Should be 10 (0A Hex). This is a flag that can be checked to see if it's a ZSoft compatible PCX. (*) even those not conform to the ZSoft specification have a 10 here, I haven't found any programs which have their own value here. 1 Version Byte The version number of the PCX file. 0 = V2.5 of PC Paintbrush 2 = V2.8 with palette 3 = V2.8 without palette 4 = PC Paintbrush for Windows (PC Paintbrush Plus for Windows uses Ver 5) 5 = Version 3.0 and higher of PC Paintbrush and PC Paintbrush + includes Publisher's Paintbrush. 2 Encoding Byte 1 = .PCX run length encoding (*) 0 = No crunching. there seem to be some files around which are not crunched with the RLE, the graphic data is stored as a raw image. 3 BitsPerPixel Byte Number of bits to represent a pixel (per plane) for PC 16 colour images this is 1. Allowed values are 1, 2, 4, 8. (*) the 24 bit images have 24 this is an extention to the PCX format which has (to my knowing) not yet been approved of by ZSoft. (*) other values are possible, some Amiga PCX files actually have 5 (32 colour) altough most 32 colour images have 1 but 5 planes. 4 XMin Word \ Image dimensions. 6 YMin Word \ XMin and YMin are usually 0 8 XMax Word / but in the PCC (PCX Blocks) the 10 YMax Word / value is actualy the screen coordinates from which the block was taken. Since counting normally starts at 0, XMax and YMax will have one less than the number of pixels per colum/row. 12 HDPI Word Horizontal resolution of image in DPI 14 VDPI Word Vertical resolution of image in DPI 16 Palette 48 bytes Colour palette setting (See later) 64 Reserved 1 byte Should be 0. (*) In Paintbrush this byte usually holds the number of the video mode the picture was made in. 65 Planes Byte Number of colour planes. 66 BytesPerLine Word Number of bytes to allocate for a scanline plane. MUST be an EVEN number. (*) A *LOT* of programs actually have an ODD number for bytesPerLine. oddly enough most PCX loaders don't load pictures correctly with an odd number. It's easy enough to accomodate this in a PCX loader. There's even a program around (forgot the name) which can write a PCX file with ODD BytesPerLine and can not read the file it just saved. 68 PaletteInfo Word How to interpret palette 1 = Color/BW 2 = Grayscale (ignored in PB IV/IV+) 70 HScreenSize Word Horizontal screen size in pixels. 72 VScreenSize Word Vertical screen size in pixels. 74 Filler 54 Bytes Blank to fill out the 128 byte header. Should all be 0. (*) Some programs store proprietary information here. When making a PCX loader you can simply ignore most values here. The ones you need are : BitsPerPixel, XMin, XMax, YMin, YMax, Planes and BytesPerLine. Depending on the type of file you'll need Version and Palette. Reading .PCX files : First find the pixel deimensions of the image by calculating XSize = XMax - XMin +1 and YSize = YMax - YMin + 1. Then calculate how many bytes are required to hold on complete uncompressed scanline : ScanlineSize = Planes * BytesPerLine. Because there are always an even number of BytesPerLine, there will probably be unused data at the end of each plane line. You can now begin decoding the first scan line, read the first byte of data from the file. if the top two bits are set, the remaining six bits in the byte show how many times to duplicate the next byte in the file. If the top two bits are not set, the first byte is the data itself, with a count of one. Following procedure can be used : while not endofscanline do begin get a byte (X) from file if the top two bits of X are 1 then begin Count = 6 lowest bits of X get a new byte (Data) from file endif else begin Count = 1 Data = X endelse Store Count bytes of Data in Output Buffer (or to screen) endwhile Continue decoding the rest of the line. Keep a running subtotal of how many bytes are moved and duplicated into the output buffer. When the subtotal equals ScanlineSize, the scanline is complete. If the subtotal is larger than ScanLineSize, the PCX file is probably corrupt. For a picture with more than one plane (16 Colour PC pictures have 4 planes), the planes are stored one after the other. Plane 0 first, Plane 3 last (the sequence of bytes will then be Red plane, Green plane, Blue plane and Intensity plane). The RLE can cross the planes, that is, it's not assured there will be a decoding break at the end of each break (subtotal equals BytesPerLine). (*) Most documentations are wrong here, stating a decoding break MUST occur at the end of each plane. They thus write PCX files with a decoding break at the end of each plane, strangely enough they do manage te READ PCX files without decoding breaks. ! SavePCX does not include a decoding break a the end of each plane. Use XSize to know what are valid pixel bits (bytes), and BytesPerLine to shows where each plane ends within the scanline. Continue decoding the remainder of the IMAGE data, (YSize scanlines). Do not just read to end-of-file. There may be additional data after the end of the image. EGA/VGA 16 Colour Palette Information. In standard RGB format, the data is stored as 16 triplets which can be found in the PCX header (Palette). Each triplet is a 3 byte quantity of Red, Green, and Blue values. The values can range from 0-255, so some interpretation may be necessary. On EGA for example, there are 4 possible levels of RGB for each color. The simplest solution is to divide each value by 64 (shift right 6 bits). On the VGA there are 64 possible levels of RGB for each colour. You will have to set the VGA DAC palette from color offsets obtained from the EGA palette registers (get it ? :-) ). VGA 256 Colour Palette. The 256 Colour palette is formatted and treated the same as the 16 colour palette, except that it is substantially longer (256 triplets). The palette (number of colours * 3 bytes per colour) is appended to the end of the .PCX file, and is preceded by a 12 (0CHex). Since the VGA DAC expects a palette value to be 0-63 in stead of 0-255, you need to divide the values read in the palette by 4 (Shift right 2 bits). To access the 256 colour palette. First check the version number in the header; if it contains a 5 there is a palette. Second, read to the end of the file and count back 769 (3*256+1) bytes. the byte you should find there is 12, showing the presence of a 256 colour palette. These two are the only types of picture which are well defined : Monochrome images, 4 colour CGA pictures : No matter what's in the Palette, the picture always seems OK, the palette information is filled with all kind of different values depending on what program created the PCX file. Simply put, treat monochrome images as Black/White whatever the value in the palette. and treat 4 colour images with the default CGA colour set (Black, Cyan, Magenta, White). (*) 32 and 64 colour images have a palette identical to the 256 colour palette, but with 32 or 64 entries in stead of 256. (*) 8 colour images can have either an 16 colour or 256 colour compatible palette. The best way to treat these images is as follows, if it has a palette appended (like the 256 colour pictures) use that one, overriding the values in the header. If there's no appended palette, use the Palette in the Header. (*) 24 Bit pictures have no palette, the pixels should be treated as 24-bit (true colour). To display these images on a standard VGA, you'll either have to dither the picture or set up a default palette and calculate an 8 bit value for each 24 bit value (colour reduction). To make a PCX Write routine, just reverse it all :-) (come on do something yourself). Just incorporate a Version 5 PCX write only, most PCX loaders read those anyway. The values in HDPI, VPDI are used for scanned images, depicting the resolution the picture was scanned at. HDPI, VDPI, PaletteInfo, VScreenSize, and HScreenSize, just leave them at 0. Fill up the Header Palette with a default EGA setting. Contacting PSI. --------------- You can contact PSI on following address : Olivier Reubens Lippenslaan 205 8300 Knokke-Heist Belgium Or you can call the PSI BBS. FUN-derbird +32-(0)50-620112 Speeds From 1200 up to 16.8k (MNP4-5, V42 & V42bis) 2.2 Gigabyte online Lots of Pascal, C, Asm sources Loads of GIF and MOD and more....... Disclaimer ---------- The software, diskettes, and documentation are provided "AS IS". There is no warranty of merchantability, no warranty of fitness for a particular use, and no warranty of any kind, either expressed or implied regarding the software, diskettes, or documentation. Accordingly, the entire risk as to the use, results and performance of the software and documentation is assumed by you. In no event will Prometheus Systems Incorporated be liable to you or any one else for any consequential, special, or indirect damages resulting from possession, use, or malfunction of this product, including without limitation, damage to property and, to the extent permitted by law, damage for personal injury, even if Prometheus Systems Incorporated has been advised of such damages or loss. Some Countries (states) do no allow limitations on the duration of implied warranties and/or the exclusion or limitation of incidental or consequential damages, and thus the preceding limitation and/or exclusions and limitations may not apply to you. This warranty gives you specific legal rights, and you may have other rights depending on the laws in your country (state). You agree that the liability of Prometheus Systems Incorporated arising out of any kind of legal claim (whether in contract, tort, or otherwise) will not exceed the amount you originally paid for the use of this product.