home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / PIXELD.ZIP / PIXELDLL.DOC < prev    next >
Text File  |  1989-09-25  |  6KB  |  127 lines
  1. PIXELDLL
  2. ---------
  3.     PIXELDLL is a simple DLL that allows a process to create
  4. VGA graphics in a full screen OS/2 protected mode session.
  5.  
  6. GENERAL NOTES
  7. --------------
  8.     Only one thread per session is allowed to access the DLL
  9. at a time.
  10.  
  11.     Available functions from the DLL are defined in the file
  12. PIXELDLL.H.  This file should be included in any programs that use
  13. the DLL.
  14.  
  15.     The DLL function CliOpenVGA must be called before any other
  16. DLL calls can be made.  Likewise, CliCloseVGA must be called after
  17. all DLL calls and before the program exits.
  18.  
  19.     The following calls to the DLL will BLOCK until the physical screen
  20. for the process calling the function comes to the foreground :
  21.  
  22.     CliOpenVGA          - Saves screen mode and state, and then sets VGA
  23.                   mode and registers screen threads for process.
  24.     CliCloseVGA         - Releases owners of screen threads and
  25.                   resets screen state and screen mode.
  26.  
  27.     PgrClrScrVGA        - Clears entire screen to given color.
  28.     PgrSaveScreenVGA    - Saves entire screen to given file.
  29.     PgrRestoreScreenVGA - Restores entire screen from given file.
  30.  
  31.     PgrSetPaletteVGA    - Sets acolor [] array value to given value.
  32.                   The proper operation of this function
  33.                   has NOT been verified.
  34.  
  35.     The following calls to the DLL will NOT BLOCK, but will be
  36. queued until the processes physical screen returns to the foreground.
  37.  
  38.     PgrGraph            - Plots object of given sType on the screen.
  39.  
  40.  
  41. NOTES ON CLIOPENVGA and CLICLOSEVGA
  42. ------------------------------------
  43.     CliOpenVGA starts two threads on behalf of the calling process :
  44. a VioSavRedrawWait thread and a VioModeWait thread.
  45.     The VioSavRedrawWait thread dynamically allocates the memory
  46. for saving the screen when a screen-switch-out occurs, and releases the
  47. memory upon restoring the screen after a screen-switch-in.  If
  48. insuffiscient memory is available, an ERROR beep will sound and the
  49. screen will not be saved (or restored when the screen-switch-in occurs).
  50.  
  51. NOTES ON PGRGRAPH
  52. ------------------
  53.     In this version of the DLL only the _PIXEL object is supported.
  54. This is due in part to the lack of CRT math functions for DLL
  55. functions that draw more complex objects, like arcs. Also, more
  56. complex objects take longer to plot.  This is a probelm if we
  57. queue 8000 arcs, return to the graphics session to plot the
  58. queued arcs, then immediately ask for a task switch.  The 8000
  59. arcs may not be completely plotted before the screen switch is
  60. forced and data may be lost.  On the other hand, 8000 queued points will
  61. redraw in a matter of seconds.
  62.     Attempts to plot any of the other sTypes defined in the header
  63. file PIXELDLL will result in an ERROR beep sounding.
  64.     When the plot queue has filled (current capacity is 8190 objects),
  65. a NOTE beep will sound.
  66.  
  67.  
  68. NOTES ON PGRSAVESCREENVGA and PGRRESTORESCREENVGA
  69. --------------------------------------------------
  70.     Theses functions allow plotted images to be moved to and
  71. from disk.  The data is stored in the file as 80 bytes for each plane, with
  72. 4 planes needed to represent every row of the image (always 480 rows).
  73.     Care must be used when saving and restoring files, due to the nature
  74. of the functions which perform these tasks. Why? The entire screen must be
  75. saved or restored before the screen is unlocked. Performing "shaky" I/O
  76. while the screen is locked is dangerous at best, so errors during I/O
  77. could result in the screen not being unlocked.  Also, disk I/O (not to
  78. mention overall processing speed), is very slow on my 10MHz Model 50.
  79. This means that if a task switch request is registered when we begin
  80. to save our screen image, the saving may not finish before the screen
  81. switch is forced and the saved image may be incomplete.  Also, I have noted
  82. that when writing to disk while the screen is locked and the system is
  83. waiting to screen-switch-out, the full 30 seconds might NOT be alloted
  84. to the process before the screen switch is forced. For these reasons, the
  85. PgrSaveScreenVGA function turns off disk verification and returns it
  86. to its previous state when finished. Also, both the saving and restoring
  87. functions run in the PRTYC_TIMECRITICAL class at PRTYD_MAXIMUM priority.
  88.  
  89.  
  90. SAMPLE PROGRAM NOTES
  91. ---------------------
  92.     The sample program HPCOS2 is an adaptation of the hypcloid
  93. program found in the original QC manual.  Run the program with no
  94. arguments to see the required command line parameters.
  95.     Make sure PIXELDLL.DLL resides in the LIBPATH setup in the
  96. CONFIG file.
  97.     After entering the required data, HPCOS2 will begin to plot
  98. points on the screen.  Feel free to switch out to another task while
  99. the figure is calculated or watch it plot.  If the plotting is in the
  100. background, a NOTE beep will sound when the plot queue is full.
  101.     When the image is draw to your liking, hit any key to save
  102. the screen and continue. After saving the screen, the program
  103. asks for new data parameters for plotting the hypcloid, restores
  104. the previous screen, and plots the new hypcloid on top of the old one.
  105. This will continue for the number of graphs specified on the command
  106. line.
  107.     The images saved on disk can be viewed with the PIXVIEW
  108. program. Run the program with no arguments to see the required
  109. command line parameters.
  110.  
  111. ENDING NOTES
  112. -------------
  113.     All functions for the DLL are written in C except for a simple
  114. ASM helper routine used for port I/O. While this helper routine is not
  115. necessary, it was nice to figure out how to do it.
  116.     I cannot guarantee the operation of the DLL on your machine, as
  117. I did not write the direct memory access routines myself.  These routines
  118. were adapted from a fine, fine book called Graphics Programming in C by
  119. Stevens.  Please use care because while it is difficult to really
  120. damage most hardware with software <?>, I understand that incorrectly
  121. using the video registers can damage the video equipment.  I have used
  122. this DLL on a 10MHz model 50 with an 8512 running OS/2 1.0 and 1.1 (all
  123. CSD's) without any problems since July of 1989.  My main use for the
  124. DLL is in generating fractal images.
  125.  
  126.  
  127.