home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / vbi / vbi.doc < prev    next >
Encoding:
Text File  |  1986-12-31  |  5.4 KB  |  116 lines
  1. Documentation for VBI, a vertical blank handler package
  2.  
  3. Copyright (C) 1987 by Amgem, Inc.
  4.  
  5. Permission is hereby granted for anyone to make or distribute copies of
  6. this program provided the copyright notice and this permission notice are
  7. retained.
  8.  
  9. This software, or software containing all or part of it, may not be sold
  10. except with express permission of the authors.
  11.  
  12. Authors:  Bill Dorsey & John Iarocci
  13.  
  14. If you have any questions or comments, the authors may be reached at
  15. The Tanj BBS, (301)-251-0675.  Updates and bug fixes may also be obtained
  16. through the above service.
  17.  
  18.  
  19. OVERVIEW:
  20.  
  21. VBI is a vertical blank handler package designed to allow easy access to the
  22. Atari STs vertical blank interrupt system.  It allows programmers to incor-
  23. porate many features which would otherwise require a multi-tasking operating
  24. system into their programs with a minimum of difficulty.  Examples of its
  25. use include alarms, blinking characters, and any other functions that need
  26. to be active all the time without getting in the way of normal program exec-
  27. ution.
  28.  
  29. The authors have successfuly used this package in a system which tells users
  30. calling in to a BBS that the BBS is down.  It runs in the background, and thus
  31. allows use of editors, compilers, games, etc. while it runs.  When the program
  32. detects a carrier detect, it sends a message to the modem, and toggles the
  33. DTR line, hanging up the modem.
  34.  
  35. Although this program has been tested and is believed to be bug-free, no
  36. guarantees are made of its functionality or suitability to any application.
  37.  
  38.  
  39. USE:
  40.  
  41. In order to use this package, you will need to compile the file vbi.c using
  42. your C compiler and generate an object file.  This object file will then be
  43. linked with any code you later generate to use the facilities in this package.
  44.  
  45. Before compiling, you may wish to change some definitions in vbi.h.  If you
  46. are using an RGB system, you will want to change the constant TICKSPERSEC to
  47. the value indicated in vbi.h.  Additionally, you may wish to change other
  48. values, such as QUANTUM, which specifies how often programs are called from
  49. the vertical blank handler.
  50.  
  51. Be very careful when using BIOS, XBIOS, and GEMDOS functions from within
  52. interrupt routines.  There is a fixed amount of register save space for
  53. calls to these functions, and when they are re-entered several times, crashes
  54. can occur without warning.  Admittedly, there are times when no alternative
  55. exists but to use calls to the operating system.  If crashes occur under
  56. these circumstances, you should first suspect a register space overflow before
  57. blaming your code, or the interrupt handler.
  58.  
  59. If there is a simple way to tell if the operating system can be called at
  60. a given time, say by checking some system variable, it would be the perfect
  61. solution to the above dilemma.  The interrupt routine could look to see if it
  62. was save to call the operating system before doing so.  If it was safe, it
  63. could go ahead, otherwise, it should wait until it is safe.
  64.  
  65. On final note.  These interrupt routines must be FAST!  They should pref-
  66. erably complete execution in a few milliseconds.  If they take much longer,
  67. the computer will be slowed down substantially.  The constant QUANTUM can
  68. be increased to relieve this problem somewhat, but the user should be aware
  69. that any routines that take longer than one vertical blank cycle with result
  70. in vertical blank interrupts being masked until their completion.
  71.  
  72. If you are using a C compiler other than the Mark Williams C compiler, you
  73. may need to make some minor modifications to the code.  The only thing that
  74. requires any explanation is the constant BP which comes from the include
  75. file basepage.h.  It is a pointer to the basepage of the program.  In Alcyon
  76. C, the external variable _base points to the basepage and would thus be used
  77. instead of BP.
  78.  
  79.  
  80. FUNCTIONS:
  81.  
  82. init() - This function initializes the vertical blank handler.  It must be
  83.          called before any vertical blank processes are created.
  84.  
  85. vbiexit() - This function does a terminate and stay resident call.  It should
  86.             be used only if the vertical blank handler is to be left active
  87.             after program termination.  Failure to use it under these circum-
  88.             stances WILL lead to your computer crashing!
  89.  
  90. remove() - This function removes the vertical blank handler.  Calling it will
  91.            also disable any existing vertical blank processes.
  92.  
  93. schedule() - This function is the vertical blank scheduler.  It should not
  94.              be referenced by the user under normal circumstances.
  95.  
  96. create(a) - This function creates vertical blank processes.  Its single arg-
  97.             ument should be a pointer to the function to be added to the vert-
  98.             ical blank proces queue.  Create will return the process id (an
  99.             integer) of the process it adds to the queue.
  100.  
  101. delete(a) - This function removes vertical blank processes.  Its single arg-
  102.             ument should be the process id of the process to be deleted.
  103.  
  104. sleep(a) - This function causes a process not to be called for a fixed amount
  105.            of time.  Its argument is the number of seconds before it is to
  106.            resume execution.  The call will return IMMEDIATELY.  It does not
  107.            take effect until the current process exits.
  108.  
  109.  
  110. FILES:
  111.  
  112. vbi.doc    - you're looking at it
  113. vbi.c      - source code for vbi handler functions
  114. vbi.h      - include file for vbi.c
  115. example.c  - an example program using vbi
  116.