ftp.whtech.com

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

/ ftp.whtech.com / ftp.whtech.com.tar / ftp.whtech.com / Geneve / 9640news / CAT38 / PPSPEC.ARK < prev next >

Wrap

Text File | 2006-10-19 | 20KB | 420 lines

? Page Pro File Formats Specification Copyright 1992 - Asgard Software All Rights Reserved INTRODUCTION Since Asgard Software released Page Pro 99 in the summer of 1989, it has become one of the most popular programs for the TI-99/4A. It has also become one of the most well-supported with dozens of packages from Asgard, and at least as many from other vendors, available by fairware, and in the public domain. In turn, the file formats used by Page Pro 99 have become "standards" in themselves. As standards mature they become better documented, and evolve to meet new requirements. This article is simultaneously a codification of the current standard, some extensions that are used by current and future Asgard Software products, and a bit of historical information that may be of general interest in explaining why Page Pro has become as popular as it has. CURRENT FILE FORMATS While the following is of interest primarily to programmers that would like to utilize Page Pro 99 pictures and fonts in their programs, it is by no means limited to programmers. PAGE PRO PICTURE FORMAT The Page Pro 99 picture format is wonderfully flexible. It is also unique in the TI-99/4A world as being the only picture format that can be addressed in a relative manner. Why is this important? It means that a program using it doesn't have to have the entire picture in memory in order to display or print it - it can grab any little piece of it as necessary. For this reason, the Page Pro 99 picture format is more appropriate for use on a computer of limited memory like the TI-99/4A than any other in use on this machine. Picture files are stored in Internal/Fixed-13 format (I/F-13). Each record of the file is 12 bytes long with the first byte reserved by the 99/4A for storing the size of the record (it is always a value of "12"). Files can be of any size, but are at least 2 records in size (actually 2 sectors on the disk since the 99/4A reserves that much space for every file). The first record of every picture file is the "header". Relative access files are read from record 0 on - but if viewed sequentially, this would be record 1 of the file. This record contains information about the size of the picture, and breaks down as follows: Record #0 Byte 1 - Number of columns in picture (x-size) Byte 2 - Number of rows in picture (y-size) Bytes 3-4* - Number of horizontal pixels in picture (x-size) Bytes 5-6* - Number of vertical pixels in picture (y-size) Bytes 7-8* - Starting record of display bitmap Bytes 9-12* - =0 (future expansion) Each Page Pro 99 "row" is 8-dots in size. Each Page Pro 99 "column" is 12-dots. Bytes 1 and 2 must be used, bytes 3-12 are optional, and are set to 0 if not in use. If the first two bytes are used for indicating the size of the picture, the picture is limited to 255 rows and 255 columns in size. This really isn't much of a limit for most applications - that would be a picture of 2,040 dots by 3,060 dots. If the values in bytes 1 and 2 are zero ("0") than bytes 3-6 should be used for the width and height of the picture. These optional "words" (2-bytes) allow you to specify a picture of up to 65,534 dots by 65,534 dots - or 8,191 columns by 5,461 rows. This facility isn't used by any current Page Pro 99 applications, but is provided for future expansion of the format. Bytes 7 and 8 combined contain the starting record of a display bitmap. This is a bitmap where every bit represents an 8x12 cell. If it is set to "1" there is picture data in the cell, if it is set to "0" there is not. Page Pro 99 figures this out when you load a picture by loading the whole picture and "remembering" which cells contain information and which don't. When the program is re-written to use this feature, it will load pictures much more quickly (but not necessar- ily print them faster). This bitmap is row oriented (meaning all of the bits for a row across are stored in as many records requiring in one block). If a picture was 24 rows and 24 columns, the bitmap would require 72 records (3 records across by 24 records down). After the header, all the following records are the picture data. Like the header, each record is 12 bytes long. Each byte is part of the ASCII representation of the hexadecimal definition of the character. The picture is stored by rows - meaning all of the data in a particular row will be stored one record after the other until the end of the row. The data would look like the following for a picture of 3 rows by 3 columns: Record #1 - Bytes 1-12 - Pattern description of picture row 1, column 1 Record #2 - Bytes 1-12 - Pattern description of picture row 1, column 2 Record #3 - Bytes 1-12 - Pattern description of picture row 1, column 3 Record #4 - Bytes 1-12 - Pattern description of picture row 2, column 1 Record #5 - Bytes 1-12 - Pattern description of picture row 2, column 2 . . . Record #9 - Bytes 1-12 - Pattern description of picture row 3, column 3 Again, each byte is a 1 by 8 pixel binary representation of the data stored at a particular row and column. To find the total number of records that a picture will contain, use the formula NUMBER_ROW * NUMBER_COLUMNS. If using the optional picture specifi- cation, use the formula (#_HORIZONTAL_DOTS / 8) * (#_VERTICAL_DOTS / 12). To find the data at a specific row R and column C, where the picture is Y rows wide and X rows tall, use the formula: RECORD_NUMBER = (R * Y) - Y + C If writing a program in a compiled language such as Fortran 99 or c99, it is best to use at least 2-byte Integer values to store the variables RECORD_NUMBER, R, C, X and Y. Finally, the following is a short Extended BASIC program to open up a picture file with the name "HEART", find the size, read in the data at the first row and column, place it in a character definition and display it: 10 ! Program to read in picture and place in a character definition 20 ! Copyright 1992 - Asgard Software 30 ! May be re-used with credit 40 ! 90 DIM D$(16) 91 DATA 0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F 92 RESTORE 91 93 FOR I=1 TO 16 94 READ D$(I) 95 NEXT I 100 ! Open picture file 110 OPEN #1:"DSK1.HEART",RELATIVE,INTERNAL,FIXED 13,INPUT 120 ! Read header 130 INPUT #1,REC 0:A$ 140 ! Find size of picture 150 X_SIZE = ASC(SEG$(A$,1,1)) 160 Y_SIZE = ASC(SEG$(A$,2,1)) 170 PRINT "Rows:",X_SIZE:"Columns:",Y_SIZE 180 ! Read in first row and column 190 INPUT #1,REC 1:A$ 200 ! Place in a character definition 210 FOR I=1 TO 12 220 B=ASC(SEG$(A$,I,1)) 230 N1=INT(B/16) 240 N2=B/16 250 C=INT((N2-N1)*16)+1 ! Get second half of byte 260 D=N1+1 ! Get first half of byte 270 F$=F$&D$(C)&D$(D) ! Add to definition 280 NEXT I 290 G$=SEG$(F$,1,8) 300 H$=SEG$(F$,9,4)&"00000000" 310 CALL CHAR(130,G$) 320 CALL CHAR(131,H$) 330 ! Now display on lines 1&2 and wait for key-press 340 CALL HCHAR(1,1,130,32) 350 CALL HCHAR(2,1,131,32) 360 CALL KEY(0,K,S) 370 IF S=0 THEN 360 380 CLOSE #1 390 END HEADLINE FONT FORMAT Headline fonts, like Page Pro 99 picture files, are the only fonts for the 99/4A that can be addressed in a relative manner on disk. This means that unlike any other font format for the TI-99/4A, there is no real limit on the size of a font (other than disk space). It is important to note that Headline fonts were derived after the release of Page Pro 99 in response to one of the limitations of the program. While Page Pro 99 is very flexible about locating pictures, it isn't particularly flexible about fonts. In fact, the program is limited to 3 types of fonts - large, small and line fonts. While the two sizes were adequate for many uses, they were found lacking for some. Headline fonts were originally created to allow you to generate large titling for newsletters, flyers, etc., through the use of the Headline Maker utility. The Headline Maker utility allows users to type a line of text, and it generates a picture file containing the text in the Headline font of your choice. The picture can then be located on a page as you would any picture in Page Pro. In a sense, Headline fonts are an after-thought. However, as their design has matured their utility has become more apparent - they have become the core of a number of Page Pro utilities - both available and in development. The Headline font format is arranged similar to the Page Pro picture format in that it consists of a header followed by data records. Headline fonts are also in the Internal/Fixed-13 format, and can be confused by some programs designed to use Page Pro pictures as picture files, and vice versa (more on avoiding that later). In a way, Headline fonts are picture fonts, in that each font letter is stored as a small picture. There are differences though. The header of a Headline font consists of the first 96 records of the file, numbered 0 to 95. They are as folllows: Record #0 - FONT DESCRIPTION RECORD This contains information about the size of the font. Byte 1 - Always has a value of 1 Byte 2 - Always has a value of 1 Bytes 3-4 - The last record of the file + 1 Byte 5 - The maximum height of the font character in rows (each row is 12 pixels high). Byte 6 - 0 (future expansion) Bytes 7-8* - Actual height of the tallest character in pixels Bytes 9-12 - 0 (future expansion) Records #1-95 - LETTER DESCRIPTION RECORDS These records contain information about each letter of the font. The ASCII value of the letter they describe can be found by adding 32 to the record number (in other words, record 1 describes the font character for ASCII value 33, or a "!"). Byte 1 - Column size of a character (width, or "x") Each column is 8 pixels wide Byte 2 - Row size of a character (height, or "y') Each row is 12 pixels high Bytes 3-4 - Starting record of the letter (the first record of the file where data for the letter is found) Bytes 5-6* - Actual pixel-width of a character Bytes 7-12 - 0 (future expansion) Please note that in record #0, bytes 7-8 are optional, and in records #1-95, bytes 5-6 are optional. These are provided to extend the font format to deal with letters of less than even column and row sizes. Records 96 and up are the actual picture data for the font. The data is arranged as outlined in the specification for Page Pro pictures. In fact, knowing the starting record of a letter's data, its height and width, you could use the example program for reading and displaying a portion of a picture to do the same for a portion of the letter. The following example program will open a Headline font, read in the information about, and calculate the starting record of each letter. 10 ! Program to read in the vital statistics of a Headline font 20 ! Copyright 1992 - Asgard Software 30 ! May be re-used with credit 40 ! 100 DIM WIDTH(95),HEIGHT(95),STARTREC(95) 110 ! Open the Headline font named "FONT_HF" 120 OPEN #1:"DSK1.FONT_HF",RELATIVE,INTERNAL,FIXED 13,INPUT 130 ! Read the Font Description Record and print maximum height 140 INPUT #1,REC 0:A$ 150 MAXHT = ASC(SEG$(A$,5,1)) 160 PRINT "The maximum height is:";MAXHT 170 ! Read in the rest of the font 180 FOR K=1 TO 95 190 INPUT #1,REC K:A$ 200 WIDTH(K) = ASC(SEG$(A$,1,1)) ! Width of letter 210 HEIGHT(K) = ASC(SEG$(A$,2,1)) ! Height of letter 230 T1 = ASC(SEG$(A$,3,1)) ! 1st byte of start record 240 T2 = ASC(SEG$(A$,4,1)) ! 2nd byte of start record 250 STARTREC(K) = (T1*256)+T2 ! First record of letter data 260 NEXT K 270 CLOSE #1 275 ! Now print the values for each letter 280 FOR K=1 TO 95 290 PRINT CHR$(K+32)&" = "&STR$(WIDTH(K))&"x"&STR$(HEIGHT(K)) 300 PRINT "First record=";STARTREC(K) 310 NEXT K 320 END OTHER PAGE PRO FILE FORMATS There are four other file formats used by Page Pro 99 - Large, Small and Line fonts, and Page files. Since the formats of these are unchanged from the documentation provided in the Page Pro 99 manuals, we will not cover them here. Future File Formats As mentioned in the introduction Page Pro 99 - or rather, actually, the Page Pro concept - is evolving. As this is being written the program itself is in the process of a major revision (for eventual release as version 2.0). Additionally, the finishing touches are being put on a major new Page Pro compatible utility - Page Pro Page Composer (hereafter Page Composer). While Page Pro 99 v2.0 features a number of tremendous advances in 99/4A page- making, the only new file formats generated are found in Page Composer. This program was designed to complement Page Pro by addressing the most glaring weaknesses of the program. It features the following: * It allows you to create, for the first time, multi-page documents using Page Pro pictures * The program supports multiple printer resolutions: the standard 480 dots across, as well as the 640 and 960 dot modes supported by most current printers * The pages of your documents can be printed either in Landscape or Portrait orientations Appropriately, the new file format introduced with Page Composer is the "Document file". DOCUMENT FILE FORMAT Document files are organized around the capabilities of Page Composer. The program allows you to have documents of any length (though, for practicality sake this is limited to 999 pages), and up to 30 pictures of any size on the page. It has no support for text other than text first stored as a picture using Page Pro 99's "clipping" function, or a utility such as Page Pro Headline Maker. Though this limits the uses of Page Composer somewhat, the program is nevertheless an ideal tool for laying out newsletters or other multi-page documents. A Document file is in Internal/Fixed-43 format. It consists of 42-byte records with a 1 byte length byte at the beginning. The header consists of the first record of the file - or record 0 - and describes what the document looks like. The header is as follows: Record #0 - DOCUMENT DESCRIPTION Bytes 1-2 - Number of pages Bytes 3-4 - Horizontal Page Resolution (480, 640 or 960) Bytes 5-6 - Orientation (1=Portrait, 2=Landscape) Bytes 7-8 - Horizontal Page Size in Page Pro 8-pixel columns Bytes 9-10 - Vertical Page Size in Page Pro 12-pixel rows Bytes 11-28 - Internal use to Page Composer Bytes 29-42 - Unused The data describing each page is organized into 30 record blocks - each page is sequentially stored as follows: Page #1 - Records 1-30 Page #2 - Records 31-60 Page #3 - Records 61-90 and so forth... Each record of each page file describes a picture on that page (hence the limit of 30 pictures per page). The data for page #1 would be stored as follows: Record #1 - PICTURE INFORMATION FOR PICTURE #1 ON PAGE #1 Bytes 1-30 - Picture filename Bytes 31-32 - Picture starting X location in columns Bytes 33-34 - Picture starting Y location in rows Bytes 35-36 - Picture X-size in columns Bytes 37-38 - Picture Y-size in rows Bytes 39-40 - Picture characteristics 1=Transparent 2=Opaque Bytes 41-42 - Number of pictures on page Record #2 - PICTURE INFORMATION FOR PICTURE #2 ON PAGE #1 (same layout as above) . . . Record #30 - PICTURE INFORMATION FOR PICTURE #30 ON PAGE #1 Actually, only Byte #40 is used for the 2 current picture printing options. The other byte is available for future expansion. While it is difficult to print Document files outside of the Page Composer environment, it isn't too difficult to write a program to create or modify these types of files. The following is an example of a program to modify some picture data on Page 1 of a Document file: 10 ! Program to create a Document file 20 ! Copyright 1992 - Asgard Software 30 ! May be re-used with credit 40 ! 100 DIM PAGEDATA$(30) 110 ! Open the document named "MYDOC" 120 OPEN #1:"DSK1.MYDOC",RELATIVE,INTERNAL,FIXED 43 130 FOR I=1 TO 30 140 LINPUT #1,REC=I:PAGEDATE$(I) 150 NEXT I 155 A=ASC(SEG$(PAGEDATA$(1),41,1))+ASC(SEG$(PAGEDATA$(1),42,1)) 156 PRINT "Number of pictures:";A 160 INPUT "Picture filename:";FN$ 170 I=LEN(FN$) 175 IF I=0 THEN 360 180 FOR J=1 TO A 190 IF SEG$(PAGEDATA$(J),1,I)=FN$ THEN 230 200 NEXT J 210 PRINT "PICTURE NOT FOUND!" 220 GO TO 160 230 PRINT "PICTURE FOUND!" 240 A$=SEG$(PAGEDATA$(J),1,2) 250 STARTX=ASC(SEG$(A$,1,1))+ASC(SEG$(A$,2,1)) ! Find starting X 260 PRINT "Starting X location:";STARTX 270 INPUT "New X location:";NEWX 280 A$=SEG$(PAGEDATA$(J),3,2) 290 STARTY=ASC(SEG$(A$,1,1))+ASC(SEG$(A$,2,1)) ! Find starting Y 300 PRINT "Starting Y location:";STARTY 310 INPUT "New Y location:";NEWX 320 PAGEDATA$(J)=SEG$(PAGEDATA$(J),5,38) 330 PAGEDATA$(J)=CHR$(0)&CHR$(NEWX)&CHR$(0)&CHR$(NEWY)&PAGEDATA$(J) 340 PRINT #1,REC=J:PAGEDATA$(J) ! Insert new values 350 GOTO 160 360 CLOSE #1 370 END SUMMARY As the Page Pro idea changes, so will the file formats that the programs in the family use. It is likely that future versions of Page Pro 99 and utilities such as Page Pro Page Composer and Page Pro Headline Maker will extend the types of files further. You will note that all extensions are designed to be "backward compatible" - in that files using extended functions will still be usable in older programs. This was deliberate - and should continue into the future. Page Pro has just begun. Page Pro 99, Page Pro Headline Maker and Page Pro Page Composer are trademarks of Asgard Software MAY BE REPRODUCED FREELY IF UNALTERED Download complete. Turn off Capture File.