Welcome to PIC_TC (Version 1.10) PIC_TC "a PIC library for Turbo C" by Dennis F. Lovely Version 1.10, June 1990 (c) copyright 1990 by CSH Services LICENCING AND SHAREWARE POLICY This version of PIC_TC is being distributed under the 'ShareWare' concept. The 'ShareWare' concept is based on three principles: 1. People need to try programs to see if they are useful. 2. Software authors can be supported directly by users. 3. Copying and networking of programs can be encouraged. Only by supporting the program authors who release valuable programs as 'ShareWare' can you encourage others to do the same. The bottom line is - if you're still using a user supported program after a couple of weeks, then it's pretty obvious that it's worth something to you, and you should send in a contribution. If user supported software works, then everyone will benefit. The user will benefit by receiving quality products at low cost, and by being able to "test drive" software thoroughly before purchasing it. The author benefits by being able to enter the commercial software arena without first needing large sources of venture capital. Why choose this route? Because of cost. As an individual, I cannot even come close to meeting the costs of marketing commercial software. Here is what I'm asking: If you like this program, and find it of use, then your registration ($25 US / $30 CDN) will be greatly appreciated and used in supporting future, improved versions. Plus, I will mail you the next update as soon as it is ready, at no additional charge. A program disk, includ- ing all source code and laser printed documentation is available for $45 US / $54 CDN, plus you still get the next update, again at no additional charge. ii What do you get for your registration? 1) the next major version will be sent to you, at no additional charge. After that, you can always get the current version for a distribution charge of $10. 2) you encourage me to keep improving and adding features to the PIC_TC library. 3) if you wish, you'll get on my mailing list for announcements of future versions and/or products. 4) you'll get support. I do not have the time to support non- registered users, but I will always make time to support registered users. What can you do with your copy of PIC_TC? Actually, just about anything you want to! Remember that PIC_TC is the copyrighted property of CSH Services. Beyond that, I would appreciate if you would: 1) Copy and freely distribute it, as long as NO fee is charged for such copying and distribution and it is distributed ONLY in its original, unmodified form. 2) Please, don't rip me off! If you'd like to distribute PIC_TC embedded in your own software for commercial gain, then please become a registered user. 3) If you are using this program in a commercial or educational environment, then I really think that you should register your copy. That way I'll stay in business and you'll be sure to get support! I really would like to hear your comments about PIC_TC. Even if you're not a registered user, feel free to let me know what you think about it. If it really stinks, then tell me about it, and be sure to let me know where it might be improved! With your comments, hopefully I can produce a better product. I can be reached at: Tel: (506) 453-4966 Fax: (506) 452-1040 during the hours of 1:00 p.m. to 3:00 p.m. EST, Monday through Friday. Please do NOT call at other times. Sorry, but I cannot accept collect calls. iii Make all cheques payable to CSH Services. Please - to help me forward updates to you, include your PRINTED name and address. If at all possible, please fill out the enclosed order form shown below. ____________________________________________________________________ ORDER FORM (please indicate the required product and disk format) Product: a) PIC_TC Registration : $ 25 / $ 30 CDN b) PIC_TC Source code + manual : $ 45 / $ 54 CDN Disk format (if applicable): c) 5 1/4" 360 kbyte d) 3 1/2" 720 kbyte Ship to: Name ...................................................... Address ................................................... City ................... State/Province ................... Zip/PC ................. Country........................... ____________________________________________________________________ Please send completed order form with your payment (US or Canadian funds) to : CSH Services Comp. 149 Site 14 SS#3 FREDERICTON New Brunswick CANADA, E3B 5W9 Please allow 21 days for delivery. PIC_TC "a PIC library for Turbo C" by Dennis F. Lovely Version 1.10, June 1990 (c) copyright 1990 by CSH Services REFERENCE MANUAL Disclaimer CSH Services makes no representation or warranties with respect to the contents hereof and specifically disclaims any implied warranties to the suitability of this program for any particular purpose. You must determine that yourself. In addition, you should understand that using a program of this type on an IBM PC or compatible has inherent risks and that you may inadvertently damage or destroy valuable programs or data. CSH Services expressly declines to assume liability for any use of this program by you, and your use of this program constitutes your agreement to hold us blameless. CSH Services reserves the right to make changes from time to time in the context hereof without obligation to notify any person or persons of such changes. Trademarks MS-DOS is a registered trademark of Microsoft Corporation. PC-DOS is a registered trademark of IBM Corporation. TURBO C is a registered trademark of Borland International Inc. PIC is a registered trademark of Lotus Development Corp. HPGL is a registered trademark of Hewlett-Packard. - 2 - TABLE OF CONTENTS Acknowledgements 3 1. INTRODUCTION ......................................... 4 2. FEATURES OF PIC_TC ................................... 5 3. SYSTEM REQUIREMENTS .................................. 6 4. FILES INCLUDED WITH PIC_TC ........................... 7 5. RUNNING THE DEMONSTRATION ............................ 8 6. QUICK REFERENCE ...................................... 9 7. COMMAND REFERENCE ................................... 10 8. FUTURE UPDATES ...................................... 28 - 3 - Acknowledgments Many months of work went into the development of PIC_TC, with several people contributing in their own way. Consequently, special thanks go to: * Tomasz W. Hruczkowski, for his endeavours through the E-mail system and file encoding for uploading this software. * My wife, for putting up with all the long hours, in the basement slaving over a hot computer, developing this package. * To ALL registered users - THANK YOU - it is only through your support that additional versions are made possible. - 4 - 1. INTRODUCTION This manual describes the use and operation of PIC_TC, a library of routines, callable from any Turbo C program, to produce graphics in the LOTUS PIC file format. This is especially useful for incorporating wordprocessor compatibility into your own graphic programs. The manual includes setup instructions, description of a demonstration program (included with this package), and full reference for all of the available functions in PIC_TC. All the functions of PIC_TC are contained in each of five different object files for Small, Medium, Compact, Large and Huge memory model environments. It is up to the user to select the appropriate object file for his/her application. Providing the user is registered, there is no additional licencing charge to incorporate these routines into commercial software under development. - 5 - 2. FEATURES OF PIC_TC The PIC_TC library contains all the basic instructions applicable to the PIC file format. These include the primitive "pen up draw" and "pen down draw" along with font and colour selection. In addition, CSH Services have included useful features such as relative drawing, scaling, rectangle drawing and block rectangle functions. In all, 17 user callable functions have been provided in PIC_TC Version 1.10 to enable the user to create graphics in the PIC file format. The format of these functions is listed briefly in Section 6: Quick Reference, while full descriptions and examples are given in Section 7: Command Reference. All of the functions return error codes which allow the user to verify that the particular operation was completed sucessfully. NOTE: The PIC_TC library does not allow the user to view PIC files, whether created by the library or from 3rd party software. To view PIC files suitable additional software is required. - 6 - 3. SYSTEM REQUIREMENTS The PIC_TC library does require that the user has a copy of TURBO C from Borland International Inc. It is also expected that the user has a working knowledge of the C programming language. The PIC_TC library can be used on any machine running PC-DOS or MS-DOS with enough memory to support the TURBO C integrated environment. No graphics card is necessary to use the software, however if the final image is to be viewed, rather than printed, then a graphics card is of course mandatory. - 7 - 4. FILES INCLUDED WITH PIC_TC There are 10 files associated with the PIC_TC library. These are listed below: PIC_TC_S.OBJ - Small memory model PIC_TC_M.OBJ - Medium memory model PIC_TC_C.OBJ - Compact memory model PIC_TC_L.OBJ - Large memory model PIC_TC_H.OBJ - Huge memory model PIC_TC.H - Prototype definitions of PIC functions DEMOPIC.EXE - Demonstration program (ready to run) DEMOPIC.C - Demonstration program (source) DEMOPIC.PRJ - Demonstration program (project make file) PIC_READ.ME - This document NOTE: It is your responsibility to make backup copies of the program disk we send you. Never use your program disk without making such a backup copy. - 8 - 5. RUNNING THE DEMONSTRATION A well commented demonstration program (DEMOPIC.C) is included with the library of routines to illustrate the use of the individual functions. This program will produce a PIC file called TRY.PIC which can be imported into LOTUS 123 or other commercial software packages to be viewed or printed. The user should first of all examine the source code to see how the library is used. In all applications the prototype definition file (PIC_TC.H) should be included at the top of any source code which calls the routines. A project make file is also included which specifies that the SMALL memory model object code should be linked with the demonstration program. The user should first bring up TURBO C in the interactive mode using the TC command. The compiler options should be set to a SMALL memory model and the project make file (DEMOPIC.PRJ) specified. The demonstration program source code (DEMOPIC.C) should be accessible to the compiler and the program built to create an executable file called (DEMOPIC.EXE). The user can either leave the TURBO C environment and run the demonstration from the DOS prompt, or run the demonstration directly using the 'Ctrl R' key combination from the TURBO C integrated environment. In either case, a brief description of the demonstration will be given and the user asked whether to continue or not. Continuation will result in the creation of a file in PIC format (TRY.PIC) which illustrates all of the functions of the TC_PIC library. This file can be viewed by several means. Firstly, using any software product which permits the importation of a PIC graphic file, eg. Lotus 123, Freelance etc. The second method of viewing the image is to use a wordprocessor which can accept PIC file formats, eg. Manuscript etc. The circles at the left hand side of the image are in different colours. The rectangular solid area to the right is in fact a series of square blocks of different colour with the colour numbers shown to the left of the blocks. The majority of the text is in font style #1 with the exception of the copywrite notice which is in font style #2. Using Lotus 123 the appearance of this image can be changed to illustrate the colours used and the different font styles. With Manuscript, and some other wordprocessors, these options are not available consequently the appearance is limited to monochrome and a single font style. - 9 - 6. QUICK REFERENCE This section is intended to be used as a quick reference to all the functions included in PIC_TC Version 1.10. This page should be photocopied and kept at hand during program development until one gets familiar with the functions. OPENING & CLOSING PIC FILE pic_open(char *filepath) opens PIC file & initialises pic_close(void) terminates plot & closes file PRIMITIVES pic_pu_move_abs(float x,float y) absolute move with pen up pic_pu_move_rel(float x,float y) relative move with pen up pic_pd_move_abs(float x,float y) absoulte move with pen down pic_pd_move_rel(float x,float y) relative move with pen down GENERAL DRAWING ATTRIBUTES pic_set_colour(int col) set drawing colour pic_set_font(int type) set character font pic_set_linetype(int type) set line type GENERAL DRAWING SCALING pic_set_cs(float x,float y) set character size pic_set_sp(int x1,int y1, set scaling points int x2,int y2) pic_set_scale(float xmin,float xmax, set drawing scale float ymin,float ymax) DRAWING COMMANDS pic_draw_rectangle(float x1,float y1, draw rectangle float x2,float y2) pic_draw_line(float x1,float y1, draw line float x2,float y2) pic_draw_block(float x1,float y1, draw filled rectangle float x2,float y2) pic_draw_circle(float x1,float y1, draw circle float r) pic_draw_text(char *text,int r, write text string int j) - 10 - 7. COMMAND REFERENCE pic_open PURPOSE: Opens and initializes a binary file in Lotus PIC format SYNTAX: int pic_open(char *filepath); EXAMPLE CALL: if(pic_open("c:\path\filename.pic")!=0){ printf("ERROR IN OPENING FILE"); return(0); } . . DESCRIPTION: Creates a binary file named by the user and writes the PIC file header and initialization bytes. It is advised that the user employ the .PIC extension to be compatible with other 3rd party software. RETURNS: The pic_open function returns 0 if a file was correctly opened. If an error occurred a code indicating the type of error is returned. Possible error codes are: 1 - error in opening file 2 - file write error - 11 - pic_close PURPOSE: Closes a PIC file previously opened using pic_open SYNTAX: int pic_close(void); EXAMPLE CALL: if(pic_close()!=0){ printf("ERROR IN CLOSING FILE"); return(0); } . . DESCRIPTION: Writes the termination code to the end of a PIC file and closes the file. RETURNS: The pic_close function returns 0 if a file was correctly closed. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 3 - error in closing file - 12 - pic_set_colour PURPOSE: Sets the current drawing colour SYNTAX: int pic_set_colour(int colour); EXAMPLE CALL: int err; . . err=pic_set_colour(2); . . DESCRIPTION: Determines the current drawing colour for subsequent draw commands. Valid colour numbers are from 1 to 8 inclusive. RETURNS: The pic_set_colour function returns 0 if a valid colour code was specified. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 7 - invalid colour code - 13 - pic_set_font PURPOSE: Sets the current font style SYNTAX: int pic_set_font(int font); EXAMPLE CALL: int err; . . err=pic_set_font(3) . . DESCRIPTION: Determines the font style to be used with subsequent text string output. Valid font numbers are from 1 to 8 inclusive. RETURNS: The pic_set_font function returns 0 if a valid font number was selected. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 6 - invalid font number - 14 - pic_set_linetype PURPOSE: Sets the current line type SYNTAX: int pic_set_linetype(int linetype); EXAMPLE CALL: int err; . . err=pic_set_linetype(3); . . DESCRIPTION: Determines the current line type for subsequent draw commands. Valid line type numbers are from 0 to 4 inclusive. The appearance of these line types are as follows: 0 - solid line 1 - broken line (line:space ratio = 1:1) 2 - broken line (line:space ratio = 1:2) 3 - broken line (line:space ratio = 1:3) 4 - dotted line NOTE: The scale of the line type is fixed at 2.5% of the distance between the scaling points and is consequently affected by scaling point changes (see pic_set_sp). RETURNS: The pic_set_linetype function returns 0 if a valid line type code was specified. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 8 - invalid line type code - 15 - pic_set_cs PURPOSE: Sets the character size for text output SYNTAX: int pic_set_cs(float width,float height); EXAMPLE CALL: int err; . . err=pic_set_cs(0.1,0.2) . . DESCRIPTION: Determines the size of text characters output by the pic_write_text command, with independent control of height and width. NOTE: The character size is specified in the same units as all the other drawing commands and is consequently affected by scale changes (see pic_set_scale). RETURNS: The pic_set_cs function returns 0 if the command was sucessfully writen to the PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 16 - pic_set_sp PURPOSE: Sets the scaling points for drawing commands SYNTAX: int pic_set_sp(int x1,int y1,int x2,int y2); EXAMPLE CALL: int err; . . err=pic_set_sp(100,200,2100,2200); . . DESCRIPTION: Determines the extents of the drawing with respect to the absolute coordinates of the PIC file format. The largest allowed drawing has the lower corner at (0,0) and the upper right hand corner at (3180,2300). NOTE: Programmers who are familiar with the Hewlett-Packard Graphics Language (HPGL) will find this function is equivalent to the SP command. RETURNS: The pic_set_sp function returns 0 if valid scaling points were specified. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 4 - scaling points out of valid range - 17 - pic_set_scale PURPOSE: Re-maps the PIC file coordinates into user coordinates SYNTAX: int pic_set_scale(float xmin,float xmax, float ymin,float ymax); EXAMPLE CALL: int err; . . err=pic_set_scale(-10.0,10.0,-10.0,10.0) . . DESCRIPTION: Maps the distance between the scaling points to a user defined coordinate system. Subsequent draw commands will use this new coordinate system. This allows the user to employ more convenient units when creating a PIC file. RETURNS: The pic_set_scale function returns 0 if valid scale was specified. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 5 - scaling factor error - 18 - pic_pu_move_abs PURPOSE: Moves with the 'pen up' to the point x,y SYNTAX: int pic_pu_move_abs(float x,float y); EXAMPLE CALL: int err; . . err=pic_pu_move_abs(8.3,-4.6); . . DESCRIPTION: Moves the current location of the 'pen' without drawing any lines. The units are as defined by the user via the pic_set_scale command. RETURNS: The pic_pu_move_abs function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 19 - pic_pu_move_rel PURPOSE: Moves with the 'pen up' relative to the last point SYNTAX: int pic_pu_move_rel(float x,float y); EXAMPLE CALL: int err; float width,height; . . pic_set_cs(width,height); pic_pu_move_abs(5,5); pic_write_text("line 1",0,0); err=pic_pu_move_rel(0,-height); pic_write_text("line 2",0,0); . . DESCRIPTION: Moves the current location of the pen, relative the previous location, without drawing any lines. The units are as defined by the user via the pic_set_scale command. NOTE: This command is useful for aligning text in columns (see example above). RETURN: The pic_pu_move_rel function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 20 - pic_pd_move_abs PURPOSE: Moves with the 'pen down' to the point x,y SYNTAX: int pic_pd_move_abs(float x,float y); EXAMPLE CALL: int err; . . err=pic_pd_move_abs(8.3,-4.6); . . DESCRIPTION: Moves the current location of the 'pen' drawing a line between the previous location and the new location. The units are as defined by the user via the pic_set_scale command. RETURN: The pic_pd_move_abs function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 21 - pic_pd_move_rel PURPOSE: Moves with the 'pen down' relative to the last point SYNTAX: int pic_pd_move_rel(float x,float y); EXAMPLE CALL: int err; float i,ticklength; . . pic_pu_move_abs(-5.0,0); for(i=-5.0;i<=5.0;i++){ pic_pd_move_abs(i,0); err=pic_pd_move_rel(0,-ticklength); pic_pu_move_rel(0,ticklength); } . . DESCRIPTION: Moves the current location of the pen, relative the previous location, with the pen down. The units are as defined by the user via the pic_set_scale command. NOTE: This command is useful for drawing tick marks on a graph axis (see example above). RETURN: The pic_pd_move_rel function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 22 - pic_draw_rectangle PURPOSE: Draws a rectangle SYNTAX: int pic_draw_rectangle(float x1,float y1, float x2,float y2); EXAMPLE CALL: int err; . . err=pic_draw_rectangle(-3.5,-3.5,3.5,3.5); . . DESCRIPTION: Draws a rectangle with the lower left and upper right corners specified in user units. After successful execution of the command, the current pen location is unchanged. RETURN: The pic_draw_rectangle function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 23 - pic_draw_line PURPOSE: Draws a line SYNTAX: int pic_draw_line(float x1,float y1,float x2,float y2); EXAMPLE CALL: int err; . . err=pic_draw_line(-3.5,-3.5,3.5,3.5); . . DESCRIPTION: Draws a line with the end points specified in user units. After successful execution of the command, the current pen location is unchanged. RETURN: The pic_draw_line function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 24 - pic_draw_block PURPOSE: Draws a solid filled rectangle SYNTAX: int pic_draw_block(float x1,float y1,float x2,float y2); EXAMPLE CALL: int err; . . err=pic_draw_block(-3.5,-3.5,3.5,3.5); . . DESCRIPTION: Draws a rectangle with the lower left and upper right corners specified in user units and fills the rectangle with the current selected colour (see pic_set_colour). After successful execution of the command, the current pen location is unchanged. RETURN: The pic_draw_block function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error - 25 - pic_draw_circle PURPOSE: Draws a circle SYNTAX: int pic_draw_circle(float x,float y,float radius); EXAMPLE CALL: int err; . . err=pic_draw_circle(0,0,3.5); . . DESCRIPTION: Draws a circle centred on the specified user coordinates with a given radius. After successful execution of the command, the current pen location is set to the centre of the circle. In Version 1.1 the circle is drawn in a solid line type (ie. type 0). RETURN: The pic_draw_circle function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 11- invalid radius specified - 26 - pic_draw_text PURPOSE: Writes a text string at the current pen location SYNTAX: int pic_draw_text(char *textstring,int rotation, int justify); EXAMPLE CALL: int err; . . err=pic_draw_text("Hello world",0,1); . . DESCRIPTION: Writes a text string at the current pen location using the current font and character size. The angle of the text can be specified along with the justification with respect to the current pen location. The 'rotation' argument can take values from 0 to 3 inclusive. This argument controls the angle the text makes with the horizontal. The convention adopted is shown below: 0 - 0[degree] - left to right 1 - 90[degree] CCW - bottom to top 2 - 180[degree] CCW - right to left 3 - 270[degree] CCW - top to bottom (...continued overpage) - 27 - pic_draw_text ... continued The 'justify' argument can take values from 0 to 8 inclusive. This variable determines the orientation of the text string with respect to the current pen location. The convention adopted is shown below: 0 - centred vertically : centre 1 - centred vertically : right 2 - centred horizontally : under 3 - centred vertically : left 4 - centred horizontally : above 5 - right : below 6 - left : below 7 - right : above 8 - left : above RETURN: The pic_draw_text function returns 0 if the appropriate commands were written to the opened PIC file. If an error occurred a code indicating the type of error is returned. Possible error codes are: 2 - file write error 9 - invalid justification 10- invalid rotation angle - 28 - 8. FUTURE UPDATES Additional functions are being developed at present to enhance the PIC_TC package. A summary of these improvements are listed below: * Windowing features to mimic the HPGL command IW. * The circle command is being developed to reflect the current line type. * An aspect ratio command to automatically set the drawing limits. This update will be sent free of charge to all registered users by Fall 1990. CSH Services solicitates feedback with regard to this development and encourages user to define their needs.