home *** CD-ROM | disk | FTP | other *** search
/ 8bitfiles.net/archives / archives.tar / archives / genie-commodore-file-library / C128CPM / SGTOOL15.ARC / SGCTOOLS.DOC < prev    next >
Encoding:
Text File  |  1993-12-01  |  8.3 KB  |  217 lines
  1. ___________________________________________________________________
  2.  
  3.                          SG C Tools 1.5
  4.                     (C) 1993 Steve Goldsmith
  5.                        All Rights Reserved
  6. ___________________________________________________________________
  7.  
  8.  
  9. NOTICE
  10.  
  11. THIS IS NOT FREE SOFTWARE!  If you paid a public domain vendor or
  12. communications service for this product, you paid for the service
  13. of copying or transferring the product, and not for the product
  14. itself.  I guarantee you that nothing ever gets to the originator
  15. of this product from such a sale.  You may evaluate this product,
  16. but if you make use of it, you must register your copy.
  17.  
  18. I offer several incentives for you to register.  First of all,
  19. you receive the most up-to-date copy that I have which is updated
  20. on a regular basis.  Unregistered releases do not include source
  21. files for the library code.  Support via GEnie, Internet, US Mail
  22. or phone from the author.
  23.  
  24.  
  25. REGISTRATION INFORMATION
  26.  
  27. The non-commercial registration fee for SG C Tools 1.5 is $10.00
  28. plus $3.00 for shipping in US funds.
  29.  
  30. Send a check or money order for the appropriate amount to:
  31.  
  32. Steve Goldsmith
  33. 2805 Jamaica Street
  34. Sarasota, FL 34231
  35.  
  36. Please indicate what product you are ordering and if you have a
  37. requirement for 3.5" media.  I normally ship 5.25" Commodore GCR
  38. format diskettes, but will furnish 3.5" media upon request.
  39. Customers outside of the United States and Canada should include
  40. $5.00 for airmail.
  41.  
  42. If you are a registered user of this product and desire an update,
  43. please contact me for upgrade prices.
  44.  
  45.  
  46. DISTRIBUTION NOTICE
  47.  
  48. This is "user-supported" software.  You are hereby granted a
  49. license by Steve Goldsmith to distribute this evaluation copy of SG
  50. C Tools and its documentation, subject to the following conditions:
  51.  
  52. 1.   SG C Tools may be distributed freely without charge in
  53.      evaluation form only.
  54.  
  55. 2.   SG C Tools may not be sold, licensed, or a fee charged for its
  56.      use.  If a fee is charged in connection with SG C Tools, it
  57.      must cover the cost of copying or dissemination only.  Such
  58.      charges must be clearly identified as such by the originating
  59.      party.  Under no circumstances may the purchaser be given the
  60.      impression that he is buying SG C Tools itself.
  61.  
  62. 3.   SG C Tools must be presented as a complete unit, including
  63.      this documentation.   Neither SG C Tools nor its documentation
  64.      may be amended or altered in any way.
  65.  
  66. 4.   By granting you the right to distribute the evaluation form of
  67.      SG C Tools, you do not become the owner of SG C Tools in any
  68.      form.  Any other use, distribution or representation of SG C
  69.      Tools is expressly forbidden without the written consent of
  70.      Steve Goldsmith.
  71.  
  72. Commodore 128 is a trademark of Commodore Business Machines.  CP/M
  73. and CP/M 3.0 are trademarks of Digital Research.  MS-DOS and
  74. Windows are trademarks of Microsoft.  IBM PC,  PC-XT and PC-AT are
  75. trademarks of International Business Machines.
  76.  
  77.  
  78. OVERVIEW
  79.  
  80. SG C Tools ANSI C library unlocks the power of the C128 running
  81. CP/M!  High level and low level functions are included to access
  82. the VDC, SID and CIA.  All source code is compatible with the
  83. Freeware version of Hi Tech C.  A demo is included to show you how
  84. to use most features.
  85.  
  86.  
  87. REQUIREMENTS
  88.  
  89. A C128 or C128D running CP/M 3.0 or a IBM PC running a CP/M
  90. emulator and DOS to CP/M file transfer software.
  91.  
  92. At least one 1581, two 1571s, large RAM disk or hard drive to
  93. compile on a C128.
  94.  
  95. 80 column monitor for VDC specific routines.  640 X 480 interlace
  96. graphics requires a monitor that can handle this format.
  97.  
  98. ANSI C programming experience.
  99.  
  100.  
  101. MODIFICATIONS IN VERSION 1.5
  102.  
  103. It took me a while to release this version due to work on another
  104. project.  I'm developing a Paradox 4.x browser for DOS and DOS
  105. Protected mode, so I haven't had much hacking time for the C128.
  106.  
  107. Added pixel, line, ellipse and text functions for VDC 640 X 480
  108. interlace bit map mode.
  109.  
  110. The 640 X 480 ellipse function leaves gaps with some radiuses.  I
  111. ported this from a Pascal SWAG packet that was intended for 320 X
  112. 240 X 256 (Mode X) VGA displays.  I may have not been intended for
  113. resolutions greater than this.  It seems to work fine in 640 X 200
  114. though.  I have included the source for this, so you can play
  115. around with it if you want.  Remember, I will give you a free
  116. registered copy for a fast integer based ellipse function which I
  117. can include in SG C Tools.
  118.  
  119. Unregistered versions no longer include library source!
  120.  
  121.  
  122. COMPILING DEMO WITH HI-TECH C 3.09
  123.  
  124. First you will need to have a copy of HI-TECH C 3.09 (CP/M-80). 
  125. You can download the following Freeware files from GEnie's CP/M RT
  126. (M685;3) or other source:
  127.  
  128.  8149 LIBSRC.LZH               X BRIAN-CPM    930616   80384     39 
  129.  3
  130.       Desc: Source Code to Hitech C library
  131.  8148 Z80V309.LZH              X BRIAN-CPM    930616  194304     51 
  132.  3
  133.       Desc: Hitech C Compiler for CP/M
  134.  8147 Z80DOC.LZH               X BRIAN-CPM    930616   89088     55 
  135.  3
  136.       Desc: Documentation for Hitech C compiler
  137.  
  138. You should look over HI-TECH C's manual and compile a simple "hello
  139. world" program before proceeding.  I installed all the compiler
  140. related files on my 1581.  My source and header files are on a
  141. 1571.  You could get away with two 1571s, but a RAM disk or hard
  142. drive would be better.  You could also use a faster CP/M system or
  143. a Z80 emulator to edit and compile code on other platforms.
  144.  
  145. To compile demo program use:
  146.  
  147. C -O -X DEMO.C -LC128
  148.  
  149.  
  150. PROGRAMMING CONSIDERATIONS
  151.  
  152. The VDC should be configured to its default CP/M 3.0 settings at
  153. the start and end of each program.
  154.  
  155. Display memory        0000h
  156. Attribute memory      0800h
  157. Character definitions 2000h
  158.  
  159. This includes restoring character definitions if you use memory at
  160. 2000h for bit maps, etc.  Setting the VDC to 64K mode wipes out
  161. memory used in 16K mode, so be sure to save the character
  162. definitions to a memory buffer or file before using 64K mode.  The
  163. VDC remains in 64K mode until you do a cold boot or warm boot with
  164. the C128's reset button.
  165.  
  166. Most of the VDC functions do not check parameters for range
  167. violations.  Range checking should be preformed at the application
  168. level.  There are times when you may want to write to a off screen
  169. memory location.  For this reason there is no need to waste time
  170. and code doing range checks.  Just be aware of the implications. 
  171. A renegade program may accidentally wipe out character definitions
  172. or other important memory regions forcing you to reboot.
  173.  
  174. Basically, just return to CP/M the way it was before your program
  175. ran.  See DEMO.C for a complete example of setting various VDC
  176. modes and exiting back to CP/M correctly.
  177.  
  178. CP/M relies on the CIAs for communication to the outside world just
  179. like in native 64/128 modes.  With this in mind it is best not to
  180. change certain registers.  I have found it safe to use CIA #2's TOD
  181. clock, timers A and B and disable all interrupt sources.  You can
  182. also safely read the keyboard and joy sticks via CIA #1 if you
  183. disable interrupts.  My low level key scan function reads all key
  184. positions into an array of 11 bytes.  See page 642 of the Commodore
  185. 128 Programmer's Reference for the key positions in the matrix. 
  186. You can tell joy stick signals from a key short because the joy
  187. stick shorts a whole row in the matrix instead of one bit like a
  188. key press.  See page 32 of the 1351 Mouse User's manual for more
  189. info.
  190.  
  191. CP/M uses voice 1 of the SID to produce a key click.  You can use
  192. the SID just as you would in native 128 mode with one exception. 
  193. Since CP/M writes to the SID during key presses it may affect a
  194. sound in progress.  You can disable interrupts to eliminate this
  195. problem.
  196.  
  197. The four bit Z Blaster engine requires the sound data's high
  198. nibbles to come first.  You can easily swap the nibbles once the
  199. sample is in memory if needed.  The maximum sample rate is about 15
  200. KHz.
  201.  
  202. The PCX engines for 640 X 200 and 640 X 480 require you to toggle
  203. off the disk status line.  The status line updates during disk I/O
  204. and changes the VDC update address which throws off the engines.
  205.  
  206.  
  207. HOW TO CONTACT ME
  208.  
  209. Please report any support questions, problems, suggestions, etc. to
  210. me via GEnie S.GOLDSMITH2, Internet S.GOLDSMITH2@GENIE.GEIS.COM,
  211. voice phone (813) 925-1064 or US Mail to:
  212.  
  213. Steve Goldsmith
  214. 2805 Jamaica Street
  215. Sarasota, FL 34231
  216. USA
  217.