home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxgd101.zip / readme.rx < prev    next >
Text File  |  1995-09-29  |  15KB  |  446 lines
  1. Hi and welcome to RXGDUTIL - The Rexx extensions to support building
  2. GIF files.  My name is Andy Wysocki (awysocki@bearsoft.com)  I found
  3. this great GD support code to build GIF files.  But since I am hooked
  4. on REXX I wanted to build GIF files from REXX.  So I created the
  5. Rxgdutil.C support module for REXX.  You take this code AS-IS and no
  6. warrenty is implied.  I provide the RXGDUTIL.DLL already made so you don't
  7. really need the rest of the stuff, but its here just incase you find a
  8. bug or want to add some functions.
  9.  
  10.  To test the .DLL you can just run the SAMPLE.CMD file and it will create
  11. an .GIF file called ANDYNEW.GIF  Thats all there is to it.  You can play
  12. around with the sample .CMD file to see what all the function do.  I am
  13. not a graphics person so my sample code is not very exciting.   So on with
  14. the rest of the RXGDUTIL manual.
  15.  
  16.   This is a QUICKLY typed up a REXX manual.  To understand completely all
  17. the 'gd' function I would suggest looking the gd.zip file and looking at the
  18. .HTML document.  Or better yet viewing they GD home page.
  19.  
  20. http://sunsite.unc.edu/boutell/index.html
  21.  
  22. Tom has a bunch of other libraries/support code to help with other functions
  23. in life, I would suggest also checking them out.
  24.  
  25. -------------------------------
  26. Installation:
  27.  
  28. If you already unzip'ed this module then you have installed it.  If you plan
  29. on using these functions, then you MUST put the RXGDUTIL.DLL in a directory
  30. that is in your LIBPATH or always run the REXX .CMD files from the directory
  31. where the RXGDUTIL.DLL is.
  32.  
  33.  
  34. -------------------------------
  35. Legal Stuff:
  36.  
  37.  
  38. gd 1.2 is copyright 1994, 1995, Quest Protein Database Center,
  39. Cold Spring Harbor Labs. Permission granted to copy and distribute
  40. this work provided that this notice remains intact. Credit
  41. for the library must be given to the Quest Protein Database Center,
  42. Cold Spring Harbor Labs, in all derived works. This does not
  43. affect your ownership of the derived work itself, and the intent
  44. is to assure proper credit for Quest, not to interfere with your
  45. use of gd. If you have questions, ask. ("Derived works"
  46. includes all programs that utilize the library. Credit must
  47. be given in user-visible documentation.)
  48.  
  49. If you wish to release modifications to gd,
  50. please clear them first by sending email to
  51. boutell@boutell.com; if this is not done, any modified version of the gd
  52. library must be clearly labeled as such.
  53.  
  54. The Quest Protein Database Center is funded under Grant P41-RR02188 by
  55. the National Institutes of Health.
  56.  
  57. Written by http://sunsite.unc.edu/boutell/index.html  Thomas Boutell 2/94-7/95
  58.  
  59. The GIF compression code is based on that found in the pbmplus
  60. utilities, which in turn is based on GIFENCOD by David Rowley. See the
  61. notice below:
  62.  
  63.  
  64. /*
  65. ** Based on GIFENCOD by David Rowley <mgardi@watdscu.waterloo.edu>.A
  66. ** Lempel-Zim compression based on "compress".
  67. **
  68. ** Modified by Marcel Wijkstra <wijkstra@fwi.uva.nl>
  69. **
  70. ** Copyright (C) 1989 by Jef Poskanzer.
  71. **
  72. ** Permission to use, copy, modify, and distribute this software and its
  73. ** documentation for any purpose and without fee is hereby granted, provided
  74. ** that the above copyright notice appear in all copies and that both that
  75. ** copyright notice and this permission notice appear in supporting
  76. ** documentation.  This software is provided "as is" without express or
  77. ** implied warranty.
  78. **
  79. ** The Graphics Interchange Format(c) is the Copyright property of
  80. ** CompuServe Incorporated.  GIF(sm) is a Service Mark property of
  81. ** CompuServe Incorporated.
  82. */
  83.  
  84.  
  85.  
  86. The GIF decompression is based on that found in the pbmplus
  87. utilities, which in turn is based on GIFDECOD by David Koblas. See the
  88. notice below:
  89.  
  90. /* +-------------------------------------------------------------------+ */
  91. /* | Copyright 1990, 1991, 1993, David Koblas.  (koblas@netcom.com)    | */
  92. /* |   Permission to use, copy, modify, and distribute this software   | */
  93. /* |   and its documentation for any purpose and without fee is hereby | */
  94. /* |   granted, provided that the above copyright notice appear in all | */
  95. /* |   copies and that both that copyright notice and this permission  | */
  96. /* |   notice appear in supporting documentation.  This software is    | */
  97. /* |   provided "as is" without express or implied warranty.           | */
  98. /* +-------------------------------------------------------------------+ */
  99.  
  100.  
  101. And don't forget that Andrew J. Wysocki (Andy) wrote the RXGDUTIL.C
  102. module and should get all credit where credit is due. September 1995
  103.  
  104.  
  105.  
  106. -------------------------------
  107. Whats all Here:
  108.  
  109. Since I am using somebody else's code for the GIF stuff, I have included
  110. a .ZIP file in my zip file.  The original file was a TAR.Z file but I un-TARed
  111. it and just .ZIP'ed it back up.  The GD code I have included is version 1.2
  112. If you never plan on building the GD.LIB then you don't have to unzip the
  113. GD12.ZIP file.  It does have more README's and other 'C' sample code, so
  114. if this don't explain it well, then you can unzip their stuff and give it a
  115. look see.
  116.  
  117.   gd.lib        - The library I made from the GD12.ZIP file
  118.   gd.dep        - Dependency file for making the GD.LIB file
  119.   gd.mak        - Make file to compile the GD12.ZIP file to OBJ's
  120.   gd12.zip      - ORIGINAL Version 1.2 of gd.tar.Z
  121.   gdlib.cmd     - Command file to create the GD.LIB from the OBJ's
  122.   RXGDUTIL.C    - Rexx 'C' source code to call the GD.LIB functions
  123.   rxgdutil.def  - Exports of the functions from RXGDUTIL.DLL
  124.   RXGDUTIL.DEP  - Dep file for building RXGDUTIL.DLL
  125.   RXGDUTIL.MAK  - Make file to put it all together
  126.   MM.CMD        - Command file to build .OBJ's and .DLL
  127.  
  128.   GI.CMD        - Graphic Info, Sample stuff for displaying GIF info
  129.  
  130.   sample.cmd    - Stupid sample code to build a GIF file
  131.   env.gif       - .GIF file used as a brush in sample.cmd
  132.   SETINT.CMD    - Set the Interlace bit in a .GIF file
  133.   GIFDate.cmd   - Create a GIF file with the current date & time
  134.  
  135.  
  136. -------------------------------
  137. Support
  138.  
  139. You can reach me the author of 'RXGDUTIL' at
  140. http://www.bearsoft.com/abs/rxgdutil.html
  141. awysocki@bearsoft.com
  142.  
  143. You can reach the author of 'gd' at
  144. http://sunsite.unc.edu/boutell/index.html
  145. http://siva.cshl.org/gd/gd.html
  146. boutell@boutell.com
  147.  
  148.  
  149. -------------------------------
  150. Function calls:
  151.  
  152. im=RxgdImageCreate(x, y)
  153.    - Create an image in memory
  154.    x - How wide
  155.    y - How tall
  156.  
  157.    im - Returned Image Handle (1 = Not created, anything else is GOOD)
  158.  
  159.  
  160.    ...
  161.    im = RxgdImageCreate(100, 50)
  162.    ...
  163.  
  164. im=RxgdImageCreateFromGIF(filename)
  165.    - Create and image from a GIF file
  166.    filename - Gif Path and file name
  167.  
  168.    im - Returned image handle
  169.  
  170.    ...
  171.    im = RxgdImageCreateFromGIF("env.gif")
  172.    ...
  173.  
  174.  
  175. RxgdImageDestroy(im)
  176.    - Release the Image from Memory (*** THIS IS A MUST DO ***)
  177.  
  178.    im - The image file to release
  179.  
  180.    ...
  181.    Call RxgdImageDestroy im
  182.    ...
  183.  
  184.  
  185. RxgdImageGIF(filename)
  186.    - Write a GIF file from Memory to a flat file
  187.  
  188.    filename - is the file name to save the image as
  189.  
  190.    ...
  191.    Call RxgdImageGIF "Andy.GIF"
  192.    ...
  193.  
  194.  
  195. RxgdImageSetPixel(im, x, y, color)
  196.    - Set a specific Pixel to a color index
  197.  
  198.    im - Image file handle
  199.    x - X coordinate of the pixel
  200.    y - Y coordinate of the pixel
  201.    color - Color index to use 0 - 255
  202.  
  203.    ...
  204.    Call RxgdImageSetPixel im 100 150 185
  205.    ...
  206.  
  207.  
  208. RxgdImageLine(im, x1, y2, x2, y2, color)
  209.    - Draw a line between two end points
  210.  
  211.    im - Image file handle
  212.    x1 - X coordinate of the start point
  213.    y1 - Y coordinate of the start point
  214.    x2 - X coordinate of the end point
  215.    y2 - Y coordinate of the end point
  216.    color - Color Index to use (0-255)
  217.  
  218.  
  219. RxgdImagePolygon(im, points, pointsTotal, color)
  220.    - Draw a poloygon with the verticies (at least 3)
  221. RxgdImageFilledPolygon(im, points, pointsTotal Color)
  222.    - Draw a Poloygon with the Verticies and fill it with the color
  223.  
  224.    im - Image file handle
  225.    points - STEM Variable with a minimun of 3 sets of points
  226.    pointsTotal - Number of SETS in the points STEM variable
  227.    color - Color Index to use
  228.  
  229.  
  230. RxgdImageRectangle(im, x1, y1, x2, y2, color)
  231.    - Draw a rectangle with the two corners (upper left first, then lower right)
  232. RxgdImageFilledRectangle(im, x1, y1, x2, y2, color)
  233.    - Draw a rectangle with the two corners (upper left first, then lower right)
  234.      and fill it with the color
  235.  
  236.    im - Image file handle
  237.    x1, y1 - Upper left corner
  238.    x2, y2 - Lower right corner
  239.    color - Color Index to use
  240.  
  241.  
  242. RxgdImageArc(im, cx, cy, w, h, s, e, color)
  243.    - Draw and ARC or CIRCLE with the given points
  244.      To draw a circle use (im, 100, 100, 25, 25, 0, 360)
  245.      To draw a arc    use (im, 100, 100, 50, 25, 0, 180)
  246.  
  247.    im - Image file handle
  248.    cx, cy - Starting X & Y Points
  249.    w - Width
  250.    h - Height
  251.    s - Degrees Starting Point (0-360)
  252.    e - Degrees Ending Poing (0-360)
  253.  
  254. RxgdImageFillToBorder(im, x, y, border, color)
  255.    - Flood a portion of the image with the specified color
  256.  
  257.    im - Image file handle
  258.    x, y - Starting point (pixel)
  259.    border - Stopping point by color
  260.    color - Color to fill in
  261.  
  262.  
  263. RxgdImageFill(im, x, y, color)
  264.    - Floods a portion of the image with the specified color
  265.  
  266.    im - Image file handle
  267.    x, y - starting point
  268.    color - Color to use for the fill/flood
  269.  
  270.  
  271. brush=RxgdImageSetBrush(im, imbrush)
  272.    - Allow you to use another image as a brush to paint a whole picture at once
  273.  
  274.    im - Image file handle that will use the brush
  275.    imbrush - Image file handle that will be used as the brush
  276.    brush - Brush Image file handle
  277.  
  278.  
  279. tile=RxgdImageSetTile(im, imtile)
  280.    - Allow you to use another image to tile the GIF image
  281.  
  282.    im - Image file handle that will be used to tile
  283.    imtile - Image file handle that will be used as the tile
  284.    tile - Tile Image file handle
  285.  
  286.  
  287. style=RxgdImageSetStyle(im, stylestem, styleLength)
  288.    - Allows you to specify pixels for drawing dashed lines and other colorful
  289.      stuff
  290.  
  291.    im - Image file handle
  292.    stylestem - Stem variable with bit/brush pattern
  293.    styleLength - number of bit/pixel patterns
  294.    style - Style Image file handle
  295.  
  296.  
  297. stylebrush=RxgdImageGetStyleBrushed(im)
  298.    - Allows you to get the Styled Brushed image handle
  299.  
  300.    im - Image file handle
  301.    stylebrush - StyleBrushed Image file handle
  302.  
  303.  
  304. blue=RxgdImageBlue(im, color)
  305.    - Retrieves the BLUE portion of the color index
  306.  
  307.    im - Image file handle
  308.    color - color index to retrieve blue color
  309.    blue - Blue portion of the color (0-255)
  310.  
  311. red=RxgdImageRed(im, color)
  312.    - Retrieves the RED portion of the color index
  313.  
  314.    im - Image file handle
  315.    color - color index to retrieve red color
  316.    red - Red portion of the color (0-255)
  317.  
  318. green=RxgdImageGreen(im, color)
  319.    - Retrieves the GREEN portion of the color index
  320.  
  321.    im - Image file handle
  322.    color - color index to retrieve green color
  323.    green - Green portion of the color (0-255)
  324.  
  325.  
  326. pixel=RxgdImageGetPixel(im, x, y)
  327.    - Retrieve the Color Index of the pixel
  328.  
  329.    im - Image file handle
  330.    x, y - Pixel location
  331.    pixel - Color index of the pixel
  332.  
  333.  
  334. sx=RxgdImageSX(im)
  335. sy=RxgdImageSY(im)
  336.    - Retrieve the X & Y size of the Image
  337.  
  338.    im - Image file handle
  339.    sx - Width of the image
  340.    sy - Height of the image
  341.  
  342.  
  343. RxgdImageString(im, font, x, y, s, color)
  344.    - Print some text onto the GIF file at the specified location
  345. RxgdImageStringUp(im, font, x, y, s, color)
  346.    - Print some text rotated at 90 degrees onto the GIF file at the
  347.      specified location
  348.  
  349.    im - Image file handle
  350.    font - Font type currently 'T'iny, 'S'mall, 'M'ediumBold,
  351.           'L'arge, or 'G'iant
  352.    x, y - Location to start at
  353.    s - String to use
  354.    color - Color index to use for characters
  355.  
  356.  
  357. color=RxgdImageColorAllocate(im, r, g, b)
  358.    - Allocate the first available color index in the image with the specified
  359.      color, if the (256) color table is full this will return -1
  360.  
  361.    im - Image file handle
  362.    r - Red Color 0-255
  363.    g - Green color 0-255
  364.    b - Blue Color 0-255
  365.    color - Returned color index
  366.  
  367.  
  368. color=RxgdImageColorClosest(im, r, g, b)
  369.    - Find a color in the color table that is closest to the colors specified
  370. color=RxgdImageColorExact(im, r, g, b)
  371.    - Find a color in the color table that is an exact match to the
  372.      colors specified
  373.  
  374.    im - Image file handle
  375.    r - Red color 0-255
  376.    g - Green color 0-255
  377.    b - Blue color 0-255
  378.    color - returned color index if found -1 if not found
  379.  
  380.  
  381. total=RxgdImageColorsTotal(im)
  382.    - Return the number of colors in the color table
  383.  
  384.    im - Image file handle
  385.    total - the total number of colors in the color table
  386.  
  387.  
  388. interlace=RxgdImageGetInterlaced(im)
  389.    - Return if the image is interlaced or not
  390.  
  391.    im - Image file handle
  392.    interlace - returned value 1=Interlaced, 0=Not Interlaced
  393.  
  394.  
  395. RxgdImageInterlaced(im, interlace)
  396.    - Return if the image is interlaced or not
  397.  
  398.    im - Image file handle
  399.    interlace - 1=Interlaced, 0=Not Interlaced
  400.  
  401.  
  402. color=RxgdImageGetTransparent(im)
  403.    - Return the color index of the transparent color
  404.  
  405.    im - Image file handle
  406.    color - Returned color index of the color that is treated as Transparent
  407.  
  408.  
  409. RxgdImageColorTransparent(im, color)
  410.    - Return the color index of the transparent color
  411.  
  412.    im - Image file handle
  413.    color - Color index of the color that is treated as Transparent
  414.  
  415.  
  416. RxgdImageColorDeallocate(im, color)
  417.    - Remove a color from the color table and leave the entry as usable
  418.  
  419.    im - Image file handle
  420.    color - Color index of the color to deallocate
  421.  
  422.  
  423. RxgdImageCopy(imdest, imsrc, destX, destY, srcX, srcY, w, h)
  424.    - Copy a rectangular portion of one image to another image
  425.  
  426.  
  427.    imdest - Destination Image file handle
  428.    imsrc  - Source Image file handle
  429.    destX, destY - Destination starting point
  430.    srcX, srcY - Source starting point
  431.    w, h - Width and Height of the rectangle to copy.
  432.  
  433.  
  434. RxgdImageCopyResized(imdest, imsrc, destX, destY, srcX, srcY,
  435.                      destW, destH, srcW, srcH)
  436.    - Copy a rectangular portion of one image to another image.  The
  437.      destination region can vary, resulting in stretching or shrinking the
  438.      size of the image
  439.  
  440.    imdest - Destination Image file handle
  441.    imsrc - Source Image file handle
  442.    destX, destY - Destination stating point
  443.    srcX, srcY - Source starting point
  444.    destW, destH - Destination Width and Height
  445.    srcW, srcH - Source Width and Height
  446.