home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / gd201.zip / gd-2.0.1 / readme.txt < prev    next >
Text File  |  2001-04-03  |  162KB  |  3,501 lines
  1.  
  2.                             This is gd 2.0.1 BETA.
  3.                                        
  4.    _If you have problems, report them in detail, and consider using gd
  5.    1.8.4 until gd 2.0 final is out._
  6.    
  7.    The gd 2.0 documentation update is not complete, but most new features
  8.    are documented to some degree and the what's new section is reasonably
  9.    complete. Enjoy!
  10.    
  11. gd 2.0.1
  12.  
  13.   A graphics library for fast image creation
  14.   
  15.   Follow this link to the latest version of this document.
  16.   
  17.      _HEY! READ THIS!_ gd 2.0.1 creates PNG, JPEG and WBMP images, not
  18.      GIF images. This is a good thing. PNG is a more compact format, and
  19.      full compression is available. JPEG works well with photographic
  20.      images, and is still more compatible with the major Web browsers
  21.      than even PNG is. WBMP is intended for wireless devices (not
  22.      regular web browsers). Existing code will need modification to call
  23.      gdImagePng or gdImageJpeg instead of gdImageGif. _Please do not ask
  24.      us to send you the old GIF version of GD._ Unisys holds a patent on
  25.      the LZW compression algorithm, which is used in fully compressed
  26.      GIF images. The best solution is to move to legally unencumbered,
  27.      well-compressed, modern image formats such as PNG and JPEG as soon
  28.      as possible.
  29.      
  30.      gd 2.0.1 _requires_ that the following libraries also be installed:
  31.      
  32.      libpng (see the libpng home page)
  33.      
  34.      zlib (see the info-zip home page) zlib
  35.      
  36.      jpeg-6b or later, if desired (see the Independent JPEG Group home
  37.      page)
  38.      
  39.      If you want to use the TrueType font support, you must also install
  40.      the _FreeType 2.x library_, including the header files. See the
  41.      Freetype Home Page, or SourceForge. No, I cannot explain why that
  42.      site is down on a particular day, and no, I can't send you a copy.
  43.      
  44.      If you want to use the Xpm color bitmap loading support, you must
  45.      also have the X Window System and the Xpm library installed (Xpm is
  46.      often included in modern X distributions).
  47.      
  48.      Please read the documentation and install the required libraries.
  49.      Do not send email asking why png.h is not found. Do not send email
  50.      asking why libgd.so is not found, either. See the requirements
  51.      section for more information. Thank you!
  52.      
  53.   Table of Contents
  54.   
  55.      * Credits and license terms
  56.      * What's new in version "XYZ" of GD?
  57.      * What is gd?
  58.      * What if I want to use another programming language?
  59.      * What else do I need to use gd?
  60.      * How do I get gd?
  61.      * How do I build gd?
  62.      * gd basics: using gd in your program
  63.      * webpng: a useful example
  64.      * Function and type reference by category
  65.      * About the additional .gd image file format
  66.      * Please tell us you're using gd!
  67.      * If you have problems
  68.      * Alphabetical quick index
  69.        
  70.    Up to the Boutell.Com, Inc. Home Page
  71.    
  72.   Credits and license terms
  73.   
  74.    In order to resolve any possible confusion regarding the authorship of
  75.    gd, the following copyright statement covers all of the authors who
  76.    have required such a statement. _If you are aware of any oversights in
  77.    this copyright notice, please contact Thomas Boutell who will be
  78.    pleased to correct them._
  79.  
  80. COPYRIGHT STATEMENT FOLLOWS THIS LINE
  81.  
  82.      Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001
  83.      by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by
  84.      the National Institutes of Health.
  85.      
  86.      Portions copyright 1996, 1997, 1998, 1999, 2000, 2001 by
  87.      Boutell.Com, Inc.
  88.      
  89.      Portions relating to GD2 format copyright 1999, 2000 Philip Warner.
  90.      
  91.      Portions relating to PNG copyright 1999, 2000 Greg Roelofs.
  92.      
  93.      Portions relating to libttf copyright 1999, 2000 John Ellson
  94.      (ellson@lucent.com).
  95.      
  96.      Portions relating to JPEG and to color quantization copyright 2000,
  97.      Doug Becker and copyright (C) 1994-1998, Thomas G. Lane. This
  98.      software is based in part on the work of the Independent JPEG
  99.      Group. See the file README-JPEG.TXT for more information.
  100.      
  101.      Portions relating to WBMP copyright 2000 Maurice Szmurlo and Johan
  102.      Van den Brande.
  103.      
  104.      _Permission has been granted to copy, distribute and modify gd in
  105.      any context without fee, including a commercial application,
  106.      provided that this notice is present in user-accessible supporting
  107.      documentation._
  108.      
  109.      This does not affect your ownership of the derived work itself, and
  110.      the intent is to assure proper credit for the authors of gd, not to
  111.      interfere with your productive use of gd. If you have questions,
  112.      ask. "Derived works" includes all programs that utilize the
  113.      library. Credit must be given in user-accessible documentation.
  114.      
  115.      _This software is provided "AS IS."_ The copyright holders disclaim
  116.      all warranties, either express or implied, including but not
  117.      limited to implied warranties of merchantability and fitness for a
  118.      particular purpose, with respect to this code and accompanying
  119.      documentation.
  120.      
  121.      Although their code does not appear in gd 2.0.1, the authors wish
  122.      to thank David Koblas, David Rowley, and Hutchison Avenue Software
  123.      Corporation for their prior contributions.
  124.      
  125. END OF COPYRIGHT STATEMENT
  126.  
  127.   What is gd?
  128.   
  129.    gd is a graphics library. It allows your code to quickly draw images
  130.    complete with lines, arcs, text, multiple colors, cut and paste from
  131.    other images, and flood fills, and write out the result as a PNG or
  132.    JPEG file. This is particularly useful in World Wide Web applications,
  133.    where PNG and JPEG are two of the formats accepted for inline images
  134.    by most browsers.
  135.    
  136.    gd is not a paint program. If you are looking for a paint program, you
  137.    are looking in the wrong place. If you are not a programmer, you are
  138.    looking in the wrong place, unless you are installing a required
  139.    library in order to run an application.
  140.    
  141.    gd does not provide for every possible desirable graphics operation.
  142.    It is not necessary or desirable for gd to become a kitchen-sink
  143.    graphics package, but version 2.0 does include most frequently
  144.    requested features, including both truecolor and palette images,
  145.    resampling (smooth resizing of truecolor images) and so forth.
  146.    
  147.   What if I want to use another programming language?
  148.   
  149.    Not all of these tools are necessarily up to date and fully compatible
  150.    with 2.0.1.
  151.    
  152.     Perl
  153.     
  154.    gd can also be used from Perl, courtesy of Lincoln Stein's GD.pm
  155.    library, which uses gd as the basis for a set of Perl 5.x classes.
  156.    Highly recommended.
  157.    
  158.     Tcl
  159.     
  160.    gd can be used from Tcl with John Ellson's Gdtclft dynamically loaded
  161.    extension package. (Gdtclft2.0 or later is needed for gd-1.6 and up
  162.    with PNG output.)
  163.    
  164.     Pascal
  165.     
  166.    Pascal enthusiasts should look into Michael Bradbury's gdfp package.
  167.    
  168.     Haskell
  169.     
  170.    A new gd interface is now available for Haskell programmers.
  171.    
  172.     REXX
  173.     
  174.    A gd interface for the REXX language is available.
  175.    
  176.     Any Language
  177.     
  178.    There are, at the moment, at least three simple interpreters that
  179.    perform gd operations. You can output the desired commands to a simple
  180.    text file from whatever scripting language you prefer to use, then
  181.    invoke the interpreter.
  182.    
  183.      * tgd, by Bradley K. Sherman
  184.      * fly, by Martin Gleeson
  185.        
  186.   What's new in version 2.0.1?
  187.   
  188.      * Workaround for a bug in gcc, apparently found in gcc 2.7.2 and up.
  189.        I reproduced and fixed it while using gcc 2.9.5.2. The bug
  190.        occurred only when the -g option was in use. This problem caused
  191.        gcc to spew internal error messages unrelated to the correctness
  192.        of the code in gd_gd2.c. Howard Jones was first to report it.
  193.      * gdImageFilledEllipse documented and altered; no longer requires a
  194.        superfluous style argument. Thanks to Francis James Franklin.
  195.      * The Makefile now offers the correct syntax for optionally creating
  196.        a static library. Thanks to Jean-Lous Regez, among others.
  197.      * A nested comment, an attempt to return the value of a void
  198.        function, and a potentially significant error in
  199.        gdImageCopyResampled were fixed thanks to Joseph Shirley.
  200.      * A bug preventing proper truecolor text rendering was fixed, thanks
  201.        to Jason Gallagher.
  202.      * gdImageStringFT (FreeType) should now work better against a
  203.        transparent or semitransparent background, and should act in a
  204.        manner consistent with the most recent gdImageAlphaBlending
  205.        setting. Antialiasing is now done via the alpha channel mechanism
  206.        if the image is a truecolor image.
  207.      * Bugs in the output of gdImageArc and gdImageFilledArc were
  208.        reported by Bruce Verderaime. A simple and correct but inefficient
  209.        implementation has been substituted until fixes are contributed
  210.        for the faster code, which is in gd_arc_f_buggy.c along with the
  211.        test program that reproduces the bug(s).
  212.      * gdImageFilledArc now offers additional style options, which can be
  213.        combined to produce various effects.
  214.      * Masahito Yamaga (ma@yama-ga.com) sent a patch to improve support
  215.        for Japanese output via gdImageStringFT. He also added a new
  216.        readme.jpn file.
  217.      * Zillions of documentation fixes.
  218.        
  219.   What's new in version 2.0?
  220.   
  221.      * _Support for truecolor images!_ Version 2.0 can load truecolor
  222.        PNGs with no loss of color information, and almost no loss of
  223.        alpha channel information. Version 2.0 can also load truecolor
  224.        JPEGs with as little loss as possible; however, bear in mind that
  225.        JPEG is a lossy format, so repeated load/save cycles always reduce
  226.        image quality. This is not a bug. To create a truecolor image from
  227.        scratch, call the new gdImageCreateTrueColor function. The
  228.        gdImageCreate function is still available to create palette
  229.        images, and may also be referred to as gdImageCreatePalette.
  230.      * _Support for alpha channels!_ In addition to 24 bits of color
  231.        information for each pixel (eight bits of red, green, and blue
  232.        respectively), version 2.0 supports 7 bits of "alpha channel"
  233.        information. This is used to determine exactly how transparent the
  234.        pixel should be. There is also support for a full 7 bits of
  235.        transparency for each individual palette index in a palette-based
  236.        image. Please note that, as of this writing, only Macintosh
  237.        Internet Explorer 5.x and Mozilla/Netscape 6.x display partial
  238.        transparency properly.
  239.      * The new gdImageAlphaBlending function allows for two different
  240.        modes of drawing. In blending mode, the alpha channel component of
  241.        the color supplied to all drawing functions, such as
  242.        gdImageSetPixel, determines how much of the underlying color
  243.        should be allowed to shine through. The resulting image is not
  244.        transparent. In non-blending mode, drawing color is copied
  245.        literally with the alpha channel information, resulting in a
  246.        transparent image. Blending mode is not available when drawing on
  247.        palette images.
  248.      * The gdImageCopyResampled function provides "smooth" copying from a
  249.        large image to a smaller one, using a weighted average of the
  250.        pixels of the source area rather than selecting one representative
  251.        pixel. This function is identical to gdImageCopyResized when the
  252.        destination image is a palette image.
  253.      * The gdImageTrueColorToPalette function converts a truecolor image
  254.        to a palette image. The code for this function was originally
  255.        drawn from the Independent JPEG Group library code, which is
  256.        excellent. The code has been modified to preserve as much alpha
  257.        channel information as possible in the resulting palette, in
  258.        addition to preserving colors as well as possible. This does not
  259.        work as well as might be hoped. It is usually best to simply
  260.        produce a truecolor output image instead, which guarantees the
  261.        highest output quality.
  262.      * A very high degree of backwards compatibility with existing gd 1.x
  263.        code has been maintained, at both the source code and binary
  264.        level. _Code which directly accesses the pixels array will fail
  265.        only if it encounters an existing truecolor image_, which may
  266.        happen if the code attempts to open and modify an existing JPEG or
  267.        truecolor PNG. Such code should be modified to check the trueColor
  268.        flag of the gdImage structure, and refer to the tpixels array
  269.        instead when it is set.
  270.      * gd is now compiled and installed as a shared library. However, gd
  271.        still does not use autoconf, because I (TBB) have very limited
  272.        patience with autoconf. These days, most Unix systems provide a
  273.        fairly POSIX-standard environment, and the provided Makefile is
  274.        likely to work well if users read it and follow the instructions
  275.        at the top.
  276.      * Support for line thickness was added by Michael Schwartz. My
  277.        apologies to him for sitting on his patches for so long. See the
  278.        new gdImageSetThickness function, which affects all standard gd
  279.        functions that draw lines and curves. In addition, Michael added a
  280.        convenient gdImageEllipse function.
  281.      * The new gdImageFilledArc function provides a straightforward way
  282.        to draw filled arcs. Also, gdImageFilledEllipse is a convenient
  283.        way to fill an ellipse without specifying starting and ending
  284.        angles. Thanks go out to F J Franklin.
  285.      * To put an end to the confusion, TrueType 1.x support has been
  286.        removed in favor of TrueType 2.x support. The old gdImageStringTTF
  287.        function simply invokes gdImageStringFT.
  288.      * The specialized .gd and .gd2 file formats have been upgraded to
  289.        support truecolor. New images written by the versions of these
  290.        functions found in 2.0 will be rejected, with varying degrees of
  291.        grace, by older versions of gd. THIS AFFECTS THE .GD and .GD2
  292.        FORMATS ONLY. IF YOU ARE CONFUSED BY THIS PARAGRAPH, IT PROBABLY
  293.        DOESN'T APPLY TO ANYTHING YOU WILL EVER ENCOUNTER. Since these
  294.        file formats are absolutely, positively *not* designed for
  295.        distributing images, just for preprocessing them, this should not
  296.        be a big problem. gd 2.0 should read old .gd and .gd2 files
  297.        correctly.
  298.        
  299.   What's new in version 1.8.4?
  300.   
  301.      * Add support for FreeType2 (John Ellson ellson@lucent.com)
  302.      * Add support for finding in fonts in a builtin DEFAULT_FONTPATH, or
  303.        in a path from the GDFONTPATH environment variable.
  304.      * remove some unused symbols to reduce compiler warnings
  305.      * bugfix in size comparisons in gdImageCompare
  306.      * REXX now mentioned
  307.      * All memory allocation functions are now wrapped within the
  308.        library; gdFree is exported and recommended for freeing memory
  309.        returned by the gdImage(Something)Ptr family of functions.
  310.        
  311.   What's new in version 1.8.3?
  312.   
  313.      * WBMP output memory leak fixed
  314.      * #include <gd.h> corrected to #include "gd.h" in gd_wbmp.c
  315.      * Documented the fact that the source and output images shouldn't
  316.        match in the WBMP test except for black and white source images
  317.        
  318.   What's new in version 1.8.2?
  319.   
  320.      * WBMP support debugged and improved by Johann Van den Brande
  321.      * WBMP tests added to gdtest.c by Thomas Boutell
  322.      * Use of platform-dependent 'install' command removed by Thomas
  323.        Boutell
  324.      * Comments added to Makefile warning users to juggle the order of
  325.        the libraries if the linker complains; is there any portable way
  326.        to do this automatically, short of using autoconf?
  327.      * Documentation of gdImageCreateFromXpm corrected
  328.      * Updated links to fast-moving, always dodging libpng and zlib web
  329.        sites
  330.        
  331.   What's new in version 1.8.1?
  332.   
  333.      * Optional components no longer built by default (following the
  334.        documentation)
  335.      * JPEG code no longer requires inappropriate header files
  336.      * Win32 patches from Joe Gregorio
  337.      * 16-bit font support for bdftogd, from Honza Pazdziora
  338.        
  339.   What's new in version 1.8?
  340.   
  341.      * Support for JPEG output, courtesy of Doug Becker
  342.      * A link to Michael Bradbery's Pascal wrapper
  343.      * Support for WBMP output, courtesy of Maurice Szmurlo
  344.      * gdImageColorClosestHWB function based on hue, whiteness,
  345.        blackness, superior to the regular gdImageColorClosest function,
  346.        courtesy of Philip Warner
  347.      * License clarification: yes, you can modify gd
  348.        
  349.     Additional JPEG Information
  350.     
  351.    Support for reading and writing JPEG-format images is courtesy of Doug
  352.    Becker and the Independent JPEG Group / Thomas G. Lane. You can get
  353.    the latest version of the IJG JPEG software from
  354.    ftp://ftp.uu.net/graphics/jpeg/ (e.g., the jpegsrc.v6b.tar.gz file).
  355.    You _must_ use version 6b or later of the IJG JPEG software. You might
  356.    also consult the JPEG FAQ at http://www.faqs.org/faqs/jpeg-faq/.
  357.    
  358.   What's new in version 1.7.3?
  359.   
  360.    Another attempt at Makefile fixes to permit linking with all libraries
  361.    required on platforms with order- dependent linkers. Perhaps it will
  362.    work this time.
  363.    
  364.   What's new in version 1.7.2?
  365.   
  366.    An uninitialized-pointer bug in gdtestttf.c was corrected. This bug
  367.    caused crashes at the end of each call to gdImageStringTTF on some
  368.    platforms. Thanks to Wolfgang Haefelinger.
  369.    
  370.    Documentation fixes. Thanks to Dohn Arms.
  371.    
  372.    Makefile fixes to permit linking with all libraries required on
  373.    platforms with order- dependent linkers.
  374.    
  375.   What's new in version 1.7.1?
  376.   
  377.    A minor buglet in the Makefile was corrected, as well as an inaccurate
  378.    error message in gdtestttf.c. Thanks to Masahito Yamaga.
  379.    
  380.   What's new in version 1.7?
  381.   
  382.    Version 1.7 contains the following changes:
  383.      * Japanese language support for the TrueType functions. Thanks to
  384.        Masahito Yamaga.
  385.      * autoconf and configure have been removed, in favor of a carefully
  386.        designed Makefile which produces and properly installs the library
  387.        and the binaries. System-dependent variables are at the top of the
  388.        Makefile for easy modification. I'm sorry, folks, but autoconf
  389.        generated _many, many confused email messages_ from people who
  390.        didn't have things where autoconf expected to find them. I am not
  391.        an autoconf/automake wizard, and gd is a simple, very compact
  392.        library which does not need to be a shared library. I _did_ make
  393.        many improvements over the old gd 1.3 Makefile, which were
  394.        directly inspired by the autoconf version found in the 1.6 series
  395.        (thanks to John Ellson).
  396.      * Completely ANSI C compliant, according to the -pedantic-errors
  397.        flag of gcc. Several pieces of not-quite-ANSI-C code were causing
  398.        problems for those with non-gcc compilers.
  399.      * gdttf.c patched to allow the use of Windows symbol fonts, when
  400.        present (thanks to Joseph Peppin).
  401.      * extern "C" wrappers added to gd.h and the font header files for
  402.        the convenience of C++ programmers. bdftogd was also modified to
  403.        automatically insert these wrappers into future font header files.
  404.        Thanks to John Lindal.
  405.      * Compiles correctly on platforms that don't define SEEK_SET. Thanks
  406.        to Robert Bonomi.
  407.      * Loads Xpm images via the gdImageCreateFromXpm function, if the Xpm
  408.        library is available. Thanks to Caolan McNamara.
  409.        
  410.   What's new in version 1.6.3?
  411.   
  412.    Version 1.6.3 corrects a memory leak in gd_png.c. This leak caused a
  413.    significant amount of memory to be allocated and not freed when
  414.    writing a PNG image.
  415.    
  416.   What's new in version 1.6.2?
  417.   
  418.    Version 1.6.2 from John Ellson adds two new functions:
  419.      * gdImageStringTTF - scalable, rotatable, anti-aliased, TrueType
  420.        strings using the FreeType library, but only if libttf is found by
  421.        configure. _We do not provide TrueType fonts. Obtaining them is
  422.        entirely up to you._
  423.      * gdImageColorResolve - an efficient alternative for the common code
  424.        fragment:
  425.  
  426.  
  427.       if ((color=gdImageColorExact(im,R,G,B)) < 0)
  428.           if ((color=gdImageColorAllocate(im,R,G,B)) < 0)
  429.               color=gdImageColorClosest(im,R,G,B);
  430.  
  431.    Also in this release the build process has been converted to GNU
  432.    autoconf/automake/libtool conventions so that both (or either) static
  433.    and shared libraries can be built.
  434.    
  435.   What's new in version 1.6.1?
  436.   
  437.    Version 1.6.1 incorporates superior PNG reading and writing code from
  438.    Greg Roelofs, with minor modifications by Tom Boutell. Specifically, I
  439.    altered his code to read non-palette images (converting them to
  440.    palette images badly, by dithering them), and to tolerate palette
  441.    images with types of transparency that gd doesn't actually support (it
  442.    just ignores the advanced transparency features). Any bugs in this
  443.    area are therefore my fault, not Greg's.
  444.    
  445.    Unlike gd 1.6, users should have no trouble linking with gd 1.6.1 if
  446.    they follow the instructions and install all of the pieces. However,
  447.    _If you get undefined symbol errors, be sure to check for older
  448.    versions of libpng in your library directories!_
  449.    
  450.   What's new in version 1.6?
  451.   
  452.    Version 1.6 features the following changes:
  453.    
  454.    _Support for 8-bit palette PNG images has been added. Support for GIF
  455.    has been removed._ This step was taken to completely avoid the legal
  456.    controversy regarding the LZW compression algorithm used in GIF.
  457.    Unisys holds a patent which is relevant to LZW compression. PNG is a
  458.    superior image format in any case. Now that PNG is supported by both
  459.    Microsoft Internet Explorer and Netscape (in their recent releases),
  460.    we highly recommend that GD users upgrade in order to get
  461.    well-compressed images in a format which is legally unemcumbered.
  462.    
  463.   What's new in version 1.5?
  464.   
  465.    Version 1.5 featured the following changes:
  466.    
  467.    _New GD2 format_
  468.           An improvement over the GD format, the GD2 format uses the zlib
  469.           compression library to compress the image in chunks. This
  470.           results in file sizes comparable to GIFs, with the ability to
  471.           access parts of large images without having to read the entire
  472.           image into memory.
  473.           
  474.           This format also supports version numbers and rudimentary
  475.           validity checks, so it should be more 'supportable' than the
  476.           previous GD format.
  477.           
  478.    _Re-arranged source files_
  479.           gd.c has been broken into constituant parts: io, gif, gd, gd2
  480.           and graphics functions are now in separate files.
  481.           
  482.    _Extended I/O capabilities._
  483.           The source/sink feature has been extended to support GD2 file
  484.           formats (which require seek/tell functions), and to allow more
  485.           general non-file I/O.
  486.           
  487.    _Better support for Lincoln Stein's Perl Module_
  488.           The new gdImage*Ptr function returns the chosen format stored
  489.           in a block of memory. This can be directly used by the GD perl
  490.           module.
  491.           
  492.    _Added functions_
  493.           gdImageCreateFromGd2Part - allows retrieval of part of an image
  494.           (good for huge images, like maps),
  495.           gdImagePaletteCopy - Copies a palette from one image to
  496.           another, doing it's best to match the colors in the target
  497.           image to the colors in the source palette.
  498.           gdImageGd2, gdImageCreateFromGd2 - Support for new format
  499.           gdImageCopyMerge - Merges two images (useful to highlight part
  500.           of an image)
  501.           gdImageCopyMergeGray - Similar to gdImageCopyMerge, but tries
  502.           to preserve source image hue.
  503.           gdImagePngPtr, gdImageJpegPtr, gdImageWBMPPtr, gdImageGdPtr,
  504.           gdImageGd2Ptr - return memory blocks for each type of image.
  505.           gdImageCreateFromPngCtx, gdImageCreateFromGdCtx,
  506.           gdImageCreateFromGd2Ctx, gdImageCreateFromGd2PartCtx - Support
  507.           for new I/O context.
  508.           
  509.    _NOTE:_ In fairness to Thomas Boutell, any bug/problems with any of
  510.    the above features should probably be reported to Philip Warner.
  511.    
  512.   What's new in version 1.4?
  513.   
  514.    Version 1.4 features the following changes:
  515.    
  516.    Fixed polygon fill routine (again)
  517.           Thanks to Kirsten Schulz, version 1.4 is able to fill numerous
  518.           types of polygons that caused problems with previous releases,
  519.           including version 1.3.
  520.           
  521.    Support for alternate data sources
  522.           Programmers who wish to load a GIF from something other than a
  523.           stdio FILE * stream can use the new gdImageCreateFromPngSource
  524.           function.
  525.           
  526.    Support for alternate data destinations
  527.           Programmers who wish to write a GIF to something other than a
  528.           stdio FILE * stream can use the new gdImagePngToSink function.
  529.           
  530.    More tolerant when reading GIFs
  531.           Version 1.4 does not crash when reading certain animated GIFs,
  532.           although it still only reads the first frame. Version 1.4 also
  533.           has overflow testing code to prevent crashes when reading
  534.           damaged GIFs.
  535.           
  536.   What's new in version 1.3?
  537.   
  538.    Version 1.3 features the following changes:
  539.    
  540.    Non-LZW-based GIF compression code
  541.           Version 1.3 contained GIF compression code that uses simple Run
  542.           Length Encoding instead of LZW compression, while still
  543.           retaining compatibility with normal LZW-based GIF decoders
  544.           (your browser will still like your GIFs). _LZW compression is
  545.           patented by Unisys. We are currently reevaluating the approach
  546.           taken by gd 1.3. The current release of gd does not support
  547.           this approach. We recommend that you use the current release,
  548.           and generate PNG images._ Thanks to Hutchison Avenue Software
  549.           Corporation for contributing the RLE GIF code.
  550.           
  551.    8-bit fonts, and 8-bit font support
  552.           This improves support for European languages. Thanks are due to
  553.           Honza Pazdziora and also to Jan Pazdziora . Also see the
  554.           provided bdftogd Perl script if you wish to convert fixed-width
  555.           X11 fonts to gd fonts.
  556.           
  557.    16-bit font support (no fonts provided)
  558.           Although no such fonts are provided in the distribution, fonts
  559.           containing more than 256 characters should work if the
  560.           gdImageString16 and gdImageStringUp16 routines are used.
  561.           
  562.    Improvements to the "webpng" example/utility
  563.           The "webpng" utility is now a slightly more useful application.
  564.           Thanks to Brian Dowling for this code.
  565.           
  566.    Corrections to the color resolution field of GIF output
  567.           Thanks to Bruno Aureli.
  568.           
  569.    Fixed polygon fills
  570.           A one-line patch for the infamous polygon fill bug, courtesy of
  571.           Jim Mason. I believe this fix is sufficient. However, if you
  572.           find a situation where polygon fills still fail to behave
  573.           properly, please send code that demonstrates the problem, _and_
  574.           a fix if you have one. Verifying the fix is important.
  575.           
  576.    Row-major, not column-major
  577.           Internally, gd now represents the array of pixels as an array
  578.           of rows of pixels, rather than an array of columns of pixels.
  579.           This improves the performance of compression and decompression
  580.           routines slightly, because horizontally adjacent pixels are now
  581.           next to each other in memory. _This should not affect properly
  582.           written gd applications, but applications that directly
  583.           manipulate the pixels array will require changes._
  584.           
  585.   What else do I need to use gd?
  586.   
  587.    To use gd, you will need an ANSI C compiler. _All popular Windows 95
  588.    and NT C compilers are ANSI C compliant._ Any full-ANSI-standard C
  589.    compiler should be adequate. _The cc compiler released with SunOS
  590.    4.1.3 is not an ANSI C compiler. Most Unix users who do not already
  591.    have gcc should get it. gcc is free, ANSI compliant and a de facto
  592.    industry standard. Ask your ISP why it is missing._
  593.    
  594.    As of version 1.6, you also need the zlib compression library, and the
  595.    libpng library. As of version 1.6.2, you can draw text using
  596.    antialiased TrueType fonts if you also have the libttf library
  597.    installed, but this is not mandatory. zlib is available for a variety
  598.    of platforms from the zlib web site. libpng is available for a variety
  599.    of platforms from the PNG web site.
  600.    
  601.    You will also want a PNG viewer, if you do not already have one for
  602.    your system, since you will need a good way to check the results of
  603.    your work. Netscape 4.04 and higher, and Microsoft Internet Explorer
  604.    4.0 or higher, both support PNG. For some purposes you might be
  605.    happier with a package like Lview Pro for Windows or xv for X. There
  606.    are PNG viewers available for every graphics-capable modern operating
  607.    system, so consult newsgroups relevant to your particular system.
  608.    
  609.   How do I get gd?
  610.   
  611.     By HTTP
  612.     
  613.      * Gzipped Tar File (Unix)
  614.      * .ZIP File (Windows)
  615.        
  616.     By FTP
  617.     
  618.      * Gzipped Tar File (Unix)
  619.      * .ZIP File (Windows)
  620.        
  621.   How do I build gd?
  622.   
  623.    In order to build gd, you must first unpack the archive you have
  624.    downloaded. If you are not familiar with tar and gunzip (Unix) or ZIP
  625.    (Windows), please consult with an experienced user of your system.
  626.    Sorry, we cannot answer questions about basic Internet skills.
  627.    
  628.    Unpacking the archive will produce a directory called "gd-2.0.1".
  629.    
  630.     For Unix
  631.     
  632.    cd to the 2.0.1 directory. Edit the Makefile with your preferred text
  633.    editor and make any necessary changes to the settings at the top,
  634.    especially if you want Xpm or TrueType support. Next, type "make
  635.    install". Because gd 2.0 and above installs as a shared library, it is
  636.    necessary to install the library properly before running gd-based
  637.    programs.
  638.    
  639.    If you get errors, edit the Makefile again, paying special attention
  640.    to the INCLUDEDIRS and LIBDIRS settings.
  641.    
  642.    IF YOU GET LINKER ERRORS, TRY JUGGLING THE ORDER OF THE -l DIRECTIVES
  643.    IN THE MAKEFILE. Some platforms may prefer that the libraries be
  644.    listed in the opposite order.
  645.    
  646.     For Windows, Mac, Et Cetera
  647.     
  648.    Create a project using your favorite programming environment. Copy all
  649.    of the gd files to the project directory. Add gd.c to your project.
  650.    Add other source files as appropriate. Learning the basic skills of
  651.    creating projects with your chosen C environment is up to you.
  652.    
  653.    If you wish to test the library, type "make test" AFTER you have
  654.    successfully executed "make install". This will build several test
  655.    programs, including "gddemo". Run gddemo to see some of the
  656.    capabilities of gd.
  657.    
  658.    gddemo should execute without incident, creating the file demoout.png.
  659.    (Note there is also a file named demoin.png, which is provided in the
  660.    package as part of the demonstration.)
  661.    
  662.    Display demoout.png in your PNG viewer. The image should be 128x128
  663.    pixels and should contain an image of the space shuttle with quite a
  664.    lot of graphical elements drawn on top of it.
  665.    
  666.    (If you are missing the demoin.png file, the other items should appear
  667.    anyway.)
  668.    
  669.    Look at demoin.png to see the original space shuttle image which was
  670.    scaled and copied into the output image.
  671.    
  672.   gd basics: using gd in your program
  673.   
  674.    gd lets you create PNG or JPEG images on the fly. To use gd in your
  675.    program, include the file gd.h, and link with the libgd.a library
  676.    produced by "make libgd.a", under Unix. Under other operating systems
  677.    you will add gd.c to your own project.
  678.    
  679.    If you want to use the provided fonts, include gdfontt.h, gdfonts.h,
  680.    gdfontmb.h, gdfontl.h and/or gdfontg.h. For more impressive results,
  681.    install FreeType 2.x and use the new gdImageStringFT function. If you
  682.    are not using the provided Makefile and/or a library-based approach,
  683.    be sure to include the source modules as well in your project. (They
  684.    may be too large for 16-bit memory models, that is, 16-bit DOS and
  685.    Windows.)
  686.    
  687.    Here is a short example program. _(For a more advanced example, see
  688.    gddemo.c, included in the distribution. gddemo.c is NOT the same
  689.    program; it demonstrates additional features!)_
  690.    
  691. /* Bring in gd library functions */
  692. #include "gd.h"
  693.  
  694. /* Bring in standard I/O so we can output the PNG to a file */
  695. #include <stdio.h>
  696.  
  697. int main() {
  698.         /* Declare the image */
  699.         gdImagePtr im;
  700.         /* Declare output files */
  701.         FILE *pngout, *jpegout;
  702.         /* Declare color indexes */
  703.         int black;
  704.         int white;
  705.  
  706.         /* Allocate the image: 64 pixels across by 64 pixels tall */
  707.         im = gdImageCreate(64, 64);
  708.  
  709.         /* Allocate the color black (red, green and blue all minimum).
  710.                 Since this is the first color in a new image, it will
  711.                 be the background color. */
  712.         black = gdImageColorAllocate(im, 0, 0, 0);
  713.  
  714.         /* Allocate the color white (red, green and blue all maximum). */
  715.         white = gdImageColorAllocate(im, 255, 255, 255);
  716.         
  717.         /* Draw a line from the upper left to the lower right,
  718.                 using white color index. */
  719.         gdImageLine(im, 0, 0, 63, 63, white);
  720.  
  721.         /* Open a file for writing. "wb" means "write binary", important
  722.                 under MSDOS, harmless under Unix. */
  723.         pngout = fopen("test.png", "wb");
  724.  
  725.         /* Do the same for a JPEG-format file. */
  726.         jpegout = fopen("test.jpg", "wb");
  727.  
  728.         /* Output the image to the disk file in PNG format. */
  729.         gdImagePng(im, pngout);
  730.  
  731.         /* Output the same image in JPEG format, using the default
  732.                 JPEG quality setting. */
  733.         gdImageJpeg(im, jpegout, -1);
  734.  
  735.         /* Close the files. */
  736.         fclose(pngout);
  737.         fclose(jpegout);
  738.  
  739.         /* Destroy the image in memory. */
  740.         gdImageDestroy(im);
  741. }
  742.  
  743.    When executed, this program creates an image, allocates two colors
  744.    (the first color allocated becomes the background color), draws a
  745.    diagonal line (note that 0, 0 is the upper left corner), writes the
  746.    image to PNG and JPEG files, and destroys the image.
  747.    
  748.    The above example program should give you an idea of how the package
  749.    works. gd provides many additional functions, which are listed in the
  750.    following reference chapters, complete with code snippets
  751.    demonstrating each. There is also an alphabetical index.
  752.    
  753.   Webpng: a more powerful gd example
  754.   
  755.    Webpng is a simple utility program to manipulate PNGs from the command
  756.    line. It is written for Unix and similar command-line systems, but
  757.    should be easily adapted for other environments. Webpng allows you to
  758.    set transparency and interlacing and output interesting information
  759.    about the PNG in question.
  760.    
  761.    webpng.c is provided in the distribution. Unix users can simply type
  762.    "make webpng" to compile the program. Type "webpng" with no arguments
  763.    to see the available options.
  764.    
  765. Function and type reference
  766.  
  767.      * Types
  768.      * Image creation, destruction, loading and saving
  769.      * Drawing, styling, brushing, tiling and filling functions
  770.      * Query functions (not color-related)
  771.      * Font and text-handling functions
  772.      * Color handling functions
  773.      * Copying and resizing functions
  774.      * Miscellaneous Functions
  775.      * Constants
  776.        
  777.   Types
  778.   
  779.    gdImage_(TYPE)_
  780.           The data structure in which gd stores images. gdImageCreate,
  781.           gdImageCreateTrueColor and the various image file-loading
  782.           functions return a pointer to this type, and the other
  783.           functions expect to receive a pointer to this type as their
  784.           first argument. It is reasonably safe to examine any of the
  785.           members of this structure. It is also reasonably safe to modify
  786.           individual pixels within the pixels or tpixels arrays. If the
  787.           trueColor flag is set, the tpixels array is valid; otherwise
  788.           the pixels array is valid.
  789.           
  790.           The colorsTotal, red, green, blue, alpha and open arrays manage
  791.           the palette. They are valid only when the trueColor flag is not
  792.           set. The transparent value contains the palette index of the
  793.           first transparent color as read-only information for backwards
  794.           compatibility; gd 2.0 stores this information in the alpha
  795.           array so that variable transparency can be supported for each
  796.           palette entry. However, for truecolor images, transparent
  797.           represents a single RGB color which is _always 100%
  798.           transparent_, and this feature is generally supported by
  799.           browsers which do not support full alpha channels.
  800.           
  801.  
  802. typedef struct {
  803.         /* Palette-based image pixels */
  804.         unsigned char ** pixels;
  805.         int sx;
  806.         int sy;
  807.         /* These are valid in palette images only. See also
  808.         /* 'alpha', which appears later in the structure to
  809.                 preserve binary backwards compatibility */
  810.         int colorsTotal;
  811.         int red[gdMaxColors];
  812.         int green[gdMaxColors];
  813.         int blue[gdMaxColors];
  814.         int open[gdMaxColors];
  815.         /* For backwards compatibility, this is set to the
  816.                 first palette entry with 100% transparency,
  817.                 and is also set and reset by the
  818.                 gdImageColorTransparent function. Newer
  819.                 applications can allocate palette entries
  820.                 with any desired level of transparency; however,
  821.                 bear in mind that many viewers, notably
  822.                 many web browsers, fail to implement
  823.                 full alpha channel for PNG and provide
  824.                 support for full opacity or transparency only. */
  825.         int transparent;
  826.         int *polyInts;
  827.         int polyAllocated;
  828.         struct gdImageStruct *brush;
  829.         struct gdImageStruct *tile;
  830.         int brushColorMap[gdMaxColors];
  831.         int tileColorMap[gdMaxColors];
  832.         int styleLength;
  833.         int stylePos;
  834.         int *style;
  835.         int interlace;
  836.         /* New in 2.0: alpha channel for palettes. Note that only
  837.                 Macintosh Internet Explorer and (possibly) Netscape 6
  838.                 really support multiple levels of transparency in
  839.                 palettes, to my knowledge, as of 2/15/01. Most
  840.                 common browsers will display 100% opaque and
  841.                 100% transparent correctly, and do something
  842.                 unpredictable and/or undesirable for levels
  843.                 in between. TBB */
  844.         int alpha[gdMaxColors];
  845.         /* Truecolor flag and pixels. New 2.0 fields appear here at the
  846.                 end to minimize breakage of existing object code. */
  847.         int trueColor;
  848.         int ** tpixels;
  849.         /* Should alpha channel be copied, or applied, each time a
  850.                 pixel is drawn? This applies to truecolor images only.
  851.                 No attempt is made to alpha-blend in palette images,
  852.                 even if semitransparent palette entries exist.
  853.                 To do that, build your image as a truecolor image,
  854.                 then quantize down to 8 bits. */
  855.         int alphaBlendingFlag;
  856.         /* Should the alpha channel of the image be saved? This affects
  857.                 PNG at the moment; other future formats may also
  858.                 have that capability. JPEG doesn't. */
  859.         int saveAlphaFlag;
  860. } gdImage;
  861.  
  862.           The order of the structure members may appear confusing, but
  863.           was chosen deliberately to increase backwards compatibility
  864.           with existing gd 1.x-based binary code that references
  865.           particular structure members.
  866.           
  867.    gdImagePtr _(TYPE)_
  868.           A pointer to an image structure. gdImageCreate returns this
  869.           type, and the other functions expect it as the first argument.
  870.           
  871.    gdFont _(TYPE)_
  872.           A font structure. Used to declare the characteristics of a
  873.           font. Plese see the files gdfontl.c and gdfontl.h for an
  874.           example of the proper declaration of this structure. You can
  875.           provide your own font data by providing such a structure and
  876.           the associated pixel array. You can determine the width and
  877.           height of a single character in a font by examining the w and h
  878.           members of the structure. If you will not be creating your own
  879.           fonts, you will not need to concern yourself with the rest of
  880.           the components of this structure.
  881.           
  882.  
  883. typedef struct {
  884.         /* # of characters in font */
  885.         int nchars;
  886.         /* First character is numbered... (usually 32 = space) */
  887.         int offset;
  888.         /* Character width and height */
  889.         int w;
  890.         int h;
  891.         /* Font data; array of characters, one row after another.
  892.                 Easily included in code, also easily loaded from
  893.                 data files. */
  894.         char *data;
  895. } gdFont;
  896.  
  897.    gdFontPtr _(TYPE)_
  898.           A pointer to a font structure. Text-output functions expect
  899.           these as their second argument, following the gdImagePtr
  900.           argument. Two such pointers are declared in the provided
  901.           include files gdfonts.h and gdfontl.h.
  902.           
  903.    gdPoint _(TYPE)_
  904.           Represents a point in the coordinate space of the image; used
  905.           by gdImagePolygon and gdImageFilledPolygon.
  906.           
  907.  
  908. typedef struct {
  909.         int x, y;
  910. } gdPoint, *gdPointPtr;
  911.  
  912.    gdPointPtr _(TYPE)_
  913.           A pointer to a gdPoint structure; passed as an argument to
  914.           gdImagePolygon and gdImageFilledPolygon.
  915.           
  916.    gdSource _(TYPE)_
  917.  
  918. typedef struct {
  919.         int (*source) (void *context, char *buffer, int len);
  920.         void *context;
  921. } gdSource, *gdSourcePtr;
  922.  
  923.    Represents a source from which a PNG can be read. Programmers who do
  924.    not wish to read PNGs from a file can provide their own alternate
  925.    input mechanism, using the gdImageCreateFromPngSource function. See
  926.    the documentation of that function for an example of the proper use of
  927.    this type.
  928.    
  929.    gdSink _(TYPE)_
  930.  
  931. typedef struct {
  932.         int (*sink) (void *context, char *buffer, int len);
  933.         void *context;
  934. } gdSink, *gdSinkPtr;
  935.  
  936.    Represents a "sink" (destination) to which a PNG can be written.
  937.    Programmers who do not wish to write PNGs to a file can provide their
  938.    own alternate output mechanism, using the gdImagePngToSink function.
  939.    See the documentation of that function for an example of the proper
  940.    use of this type.
  941.    
  942.   Image creation, destruction, loading and saving
  943.   
  944.    gdImageCreate(sx, sy) _(FUNCTION)_
  945.           gdImageCreate is called to create palette-based images, with no
  946.           more than 256 colors. Invoke gdImageCreate with the x and y
  947.           dimensions of the desired image. gdImageCreate returns a
  948.           gdImagePtr to the new image, or NULL if unable to allocate the
  949.           image. The image must eventually be destroyed using
  950.           gdImageDestroy().
  951.           
  952.  
  953. ... inside a function ...
  954. gdImagePtr im;
  955. im = gdImageCreate(64, 64);
  956. /* ... Use the image ... */
  957. gdImageDestroy(im);
  958.  
  959.    gdImageCreateTrueColor(sx, sy) _(FUNCTION)_
  960.           gdImageCreateTrueColor is called to create truecolor images,
  961.           with an essentially unlimited number of colors. Invoke
  962.           gdImageCreateTrueColor with the x and y dimensions of the
  963.           desired image. gdImageCreateTrueColor returns a gdImagePtr to
  964.           the new image, or NULL if unable to allocate the image. The
  965.           image must eventually be destroyed using gdImageDestroy().
  966.           
  967.           Truecolor images are always filled with black at creation time.
  968.           
  969.  
  970. ... inside a function ...
  971. gdImagePtr im;
  972. im = gdImageCreateTrueColor(64, 64);
  973. /* ... Use the image ... */
  974. gdImageDestroy(im);
  975.  
  976.    gdImageCreateFromJpeg(FILE *in) _(FUNCTION)_
  977.           gdImageCreateFromJpegCtx(FILE *in) _(FUNCTION)_
  978.           
  979.    gdImageCreateFromJpeg(FILE *in) _(FUNCTION)_
  980.           gdImageCreateFromJpegCtx(FILE *in) _(FUNCTION)_
  981.           
  982.           
  983.           gdImageCreateFromJpeg is called to load images from JPEG format
  984.           files. Invoke gdImageCreateFromJpeg with an already opened
  985.           pointer to a file containing the desired image.
  986.           gdImageCreateFromJpeg returns a gdImagePtr to the new truecolor
  987.           image, or NULL if unable to load the image (most often because
  988.           the file is corrupt or does not contain a JPEG image).
  989.           gdImageCreateFromJpeg does _not_ close the file. You can
  990.           inspect the sx and sy members of the image to determine its
  991.           size. The image must eventually be destroyed using
  992.           gdImageDestroy(). _The returned image is always a truecolor
  993.           image._
  994.           
  995.  
  996. gdImagePtr im;
  997. ... inside a function ...
  998. FILE *in;
  999. in = fopen("myjpeg.jpg", "rb");
  1000. im = gdImageCreateFromJpeg(in);
  1001. fclose(in);
  1002. /* ... Use the image ... */
  1003. gdImageDestroy(im);
  1004.  
  1005.    gdImageCreateFromPng(FILE *in) _(FUNCTION)_
  1006.           gdImageCreateFromPngCtx(gdIOCtx *in) _(FUNCTION)_
  1007.           
  1008.           
  1009.           gdImageCreateFromPng is called to load images from PNG format
  1010.           files. Invoke gdImageCreateFromPng with an already opened
  1011.           pointer to a file containing the desired image.
  1012.           gdImageCreateFromPng returns a gdImagePtr to the new image, or
  1013.           NULL if unable to load the image (most often because the file
  1014.           is corrupt or does not contain a PNG image).
  1015.           gdImageCreateFromPng does _not_ close the file. You can inspect
  1016.           the sx and sy members of the image to determine its size. The
  1017.           image must eventually be destroyed using gdImageDestroy().
  1018.           
  1019.           If the PNG image being loaded is a truecolor image, the
  1020.           resulting gdImagePtr will refer to a truecolor image. If the
  1021.           PNG image being loaded is a palette or grayscale image, the
  1022.           resulting gdImagePtr will refer to a palette image. gd retains
  1023.           only 8 bits of resolution for each of the red, green and blue
  1024.           channels, and only 7 bits of resolution for the alpha channel.
  1025.           The former restriction affects only a handful of very rare
  1026.           48-bit color and 16-bit grayscale PNG images. The second
  1027.           restriction affects all semitransparent PNG images, but the
  1028.           difference is essentially invisible to the eye. 7 bits of alpha
  1029.           channel resolution is, in practice, quite a lot.
  1030.           
  1031.  
  1032. gdImagePtr im;
  1033. ... inside a function ...
  1034. FILE *in;
  1035. in = fopen("mypng.png", "rb");
  1036. im = gdImageCreateFromPng(in);
  1037. fclose(in);
  1038. /* ... Use the image ... */
  1039. gdImageDestroy(im);
  1040.  
  1041.    gdImageCreateFromPngSource(gdSourcePtr in) _(FUNCTION)_
  1042.           gdImageCreateFromPngSource is called to load a PNG from a data
  1043.           source other than a file. Usage is very similar to the
  1044.           gdImageCreateFromPng function, except that the programmer
  1045.           provides a custom data source.
  1046.           
  1047.           The programmer must write an input function which accepts a
  1048.           context pointer, a buffer, and a number of bytes to be read as
  1049.           arguments. This function must read the number of bytes
  1050.           requested, unless the end of the file has been reached, in
  1051.           which case the function should return zero, or an error has
  1052.           occurred, in which case the function should return -1. The
  1053.           programmer then creates a gdSource structure and sets the
  1054.           source pointer to the input function and the context pointer to
  1055.           any value which is useful to the programmer.
  1056.           
  1057.           The example below implements gdImageCreateFromPng by creating a
  1058.           custom data source and invoking gdImageCreateFromPngSource.
  1059.           
  1060.  
  1061. static int freadWrapper(void *context, char *buf, int len);
  1062.  
  1063. gdImagePtr gdImageCreateFromPng(FILE *in)
  1064. {
  1065.         gdSource s;
  1066.         s.source = freadWrapper;
  1067.         s.context = in;
  1068.         return gdImageCreateFromPngSource(&s);
  1069. }
  1070.  
  1071. static int freadWrapper(void *context, char *buf, int len)
  1072. {
  1073.         int got = fread(buf, 1, len, (FILE *) context);
  1074.         return got;
  1075. }
  1076.  
  1077.    gdImageCreateFromGd(FILE *in) _(FUNCTION)_
  1078.           gdImageCreateFromGdCtx(gdIOCtx *in) _(FUNCTION)_
  1079.           
  1080.           
  1081.           gdImageCreateFromGd is called to load images from gd format
  1082.           files. Invoke gdImageCreateFromGd with an already opened
  1083.           pointer to a file containing the desired image in the gd file
  1084.           format, which is specific to gd and intended for very fast
  1085.           loading. (It is _not_ intended for compression; for
  1086.           compression, use PNG or JPEG.) gdImageCreateFromGd returns a
  1087.           gdImagePtr to the new image, or NULL if unable to load the
  1088.           image (most often because the file is corrupt or does not
  1089.           contain a gd format image). gdImageCreateFromGd does _not_
  1090.           close the file. You can inspect the sx and sy members of the
  1091.           image to determine its size. The image must eventually be
  1092.           destroyed using gdImageDestroy().
  1093.           
  1094.  
  1095. ... inside a function ...
  1096. gdImagePtr im;
  1097. FILE *in;
  1098. in = fopen("mygd.gd", "rb");
  1099. im = gdImageCreateFromGd(in);
  1100. fclose(in);
  1101. /* ... Use the image ... */
  1102. gdImageDestroy(im);
  1103.  
  1104.    gdImageCreateFromGd2(FILE *in) _(FUNCTION)_
  1105.           gdImageCreateFromGd2Ctx(gdIOCtx *in) _(FUNCTION)_
  1106.           
  1107.           
  1108.           gdImageCreateFromGd2 is called to load images from gd2 format
  1109.           files. Invoke gdImageCreateFromGd2 with an already opened
  1110.           pointer to a file containing the desired image in the gd2 file
  1111.           format, which is specific to gd2 and intended for fast loading
  1112.           of parts of large images. (It is a compressed format, but
  1113.           generally not as good as maximum compression of the entire
  1114.           image would be.) gdImageCreateFromGd returns a gdImagePtr to
  1115.           the new image, or NULL if unable to load the image (most often
  1116.           because the file is corrupt or does not contain a gd format
  1117.           image). gdImageCreateFromGd2 does _not_ close the file. You can
  1118.           inspect the sx and sy members of the image to determine its
  1119.           size. The image must eventually be destroyed using
  1120.           gdImageDestroy().
  1121.           
  1122.  
  1123. ... inside a function ...
  1124. gdImagePtr im;
  1125. FILE *in;
  1126. in = fopen("mygd.gd2", "rb");
  1127. im = gdImageCreateFromGd2(in);
  1128. fclose(in);
  1129. /* ... Use the image ... */
  1130. gdImageDestroy(im);
  1131.  
  1132.    gdImageCreateFromGd2Part(FILE *in, int srcX, int srcY, int w, int h)
  1133.           _(FUNCTION)_
  1134.           gdImageCreateFromGd2PartCtx(gdIOCtx *in) _(FUNCTION)_
  1135.           
  1136.           
  1137.           gdImageCreateFromGd2Part is called to load parts of images from
  1138.           gd2 format files. Invoked in the same way as
  1139.           gdImageCreateFromGd2, but with extra parameters indicating the
  1140.           source (x, y) and width/height of the desired image.
  1141.           gdImageCreateFromGd2Part returns a gdImagePtr to the new image,
  1142.           or NULL if unable to load the image. The image must eventually
  1143.           be destroyed using gdImageDestroy().
  1144.           
  1145.    gdImageCreateFromXbm(FILE *in) _(FUNCTION)_
  1146.           gdImageCreateFromXbm is called to load images from X bitmap
  1147.           format files. Invoke gdImageCreateFromXbm with an already
  1148.           opened pointer to a file containing the desired image.
  1149.           gdImageCreateFromXbm returns a gdImagePtr to the new image, or
  1150.           NULL if unable to load the image (most often because the file
  1151.           is corrupt or does not contain an X bitmap format image).
  1152.           gdImageCreateFromXbm does _not_ close the file. You can inspect
  1153.           the sx and sy members of the image to determine its size. The
  1154.           image must eventually be destroyed using gdImageDestroy().
  1155.           
  1156.  
  1157. ... inside a function ...
  1158. gdImagePtr im;
  1159. FILE *in;
  1160. in = fopen("myxbm.xbm", "rb");
  1161. im = gdImageCreateFromXbm(in);
  1162. fclose(in);
  1163. /* ... Use the image ... */
  1164. gdImageDestroy(im);
  1165.  
  1166.    gdImageCreateFromXpm(char *filename) _(FUNCTION)_
  1167.           gdImageCreateFromXbm is called to load images from XPM X Window
  1168.           System color bitmap format files. This function is available
  1169.           only if HAVE_XPM is selected in the Makefile and the Xpm
  1170.           library is linked with the application. Unlike most gd file
  1171.           functions, the Xpm functions require filenames, not file
  1172.           pointers. gdImageCreateFromXpm returns a gdImagePtr to the new
  1173.           image, or NULL if unable to load the image (most often because
  1174.           the file is corrupt or does not contain an XPM bitmap format
  1175.           image). You can inspect the sx and sy members of the image to
  1176.           determine its size. The image must eventually be destroyed
  1177.           using gdImageDestroy().
  1178.           
  1179.  
  1180. ... inside a function ...
  1181. gdImagePtr im;
  1182. FILE *in;
  1183. in = fopen("myxpm.xpm", "rb");
  1184. im = gdImageCreateFromXpm(in);
  1185. fclose(in);
  1186. /* ... Use the image ... */
  1187. gdImageDestroy(im);
  1188.  
  1189.    gdImageDestroy(gdImagePtr im) _(FUNCTION)_
  1190.           gdImageDestroy is used to free the memory associated with an
  1191.           image. It is important to invoke gdImageDestroy before exiting
  1192.           your program or assigning a new image to a gdImagePtr variable.
  1193.           
  1194.  
  1195. ... inside a function ...
  1196. gdImagePtr im;
  1197. im = gdImageCreate(10, 10);
  1198. /* ... Use the image ... */
  1199. /* Now destroy it */
  1200. gdImageDestroy(im);
  1201.  
  1202.    void gdImageJpeg(gdImagePtr im, FILE *out, int quality) _(FUNCTION)_
  1203.           void gdImageJpegCtx(gdImagePtr im, gdIOCtx *out, int quality)
  1204.           
  1205.    _(FUNCTION)_
  1206.    
  1207.    gdImageJpeg outputs the specified image to the specified file in JPEG
  1208.    format. The file must be open for writing. Under MSDOS and all
  1209.    versions of Windows, it is important to use "wb" as opposed to simply
  1210.    "w" as the mode when opening the file, and under Unix there is no
  1211.    penalty for doing so. gdImageJpeg does _not_ close the file; your code
  1212.    must do so.
  1213.    
  1214.    If quality is negative, the default IJG JPEG quality value (which
  1215.    should yield a good general quality / size tradeoff for most
  1216.    situations) is used. Otherwise, for practical purposes, quality should
  1217.    be a value in the range 0-95, higher quality values usually implying
  1218.    both higher quality and larger image sizes.
  1219.    
  1220.    If you have set image interlacing using gdImageInterlace, this
  1221.    function will interpret that to mean you wish to output a progressive
  1222.    JPEG. Some programs (e.g., Web browsers) can display progressive JPEGs
  1223.    incrementally; this can be useful when browsing over a relatively slow
  1224.    communications link, for example. Progressive JPEGs can also be
  1225.    slightly smaller than sequential (non-progressive) JPEGs.
  1226.  
  1227. ... inside a function ...
  1228. gdImagePtr im;
  1229. int black, white;
  1230. FILE *out;
  1231. /* Create the image */
  1232. im = gdImageCreate(100, 100);
  1233. /* Allocate background */
  1234. white = gdImageColorAllocate(im, 255, 255, 255);
  1235. /* Allocate drawing color */
  1236. black = gdImageColorAllocate(im, 0, 0, 0);
  1237. /* Draw rectangle */
  1238. gdImageRectangle(im, 0, 0, 99, 99, black);
  1239. /* Open output file in binary mode */
  1240. out = fopen("rect.jpg", "wb");
  1241. /* Write JPEG using default quality */
  1242. gdImageJpeg(im, out, -1);
  1243. /* Close file */
  1244. fclose(out);
  1245. /* Destroy image */
  1246. gdImageDestroy(im);
  1247.  
  1248.    void* gdImageJpegPtr(gdImagePtr im, int *size) _(FUNCTION)_
  1249.    Identical to gdImageJpeg except that it returns a pointer to a memory
  1250.    area with the JPEG data. This memory must be freed by the caller when
  1251.    it is no longer needed. _The caller must invoke gdFree(), not free(),
  1252.    unless the caller is absolutely certain that the same implementations
  1253.    of malloc, free, etc. are used both at library build time and at
  1254.    application build time._ The 'size' parameter receives the total size
  1255.    of the block of memory.
  1256.    
  1257.    void gdImagePng(gdImagePtr im, FILE *out) _(FUNCTION)_
  1258.    gdImagePng outputs the specified image to the specified file in PNG
  1259.    format. The file must be open for writing. Under MSDOS and all
  1260.    versions of Windows, it is important to use "wb" as opposed to simply
  1261.    "w" as the mode when opening the file, and under Unix there is no
  1262.    penalty for doing so. gdImagePng does _not_ close the file; your code
  1263.    must do so.
  1264.  
  1265. ... inside a function ...
  1266. gdImagePtr im;
  1267. int black, white;
  1268. FILE *out;
  1269. /* Create the image */
  1270. im = gdImageCreate(100, 100);
  1271. /* Allocate background */
  1272. white = gdImageColorAllocate(im, 255, 255, 255);
  1273. /* Allocate drawing color */
  1274. black = gdImageColorAllocate(im, 0, 0, 0);
  1275. /* Draw rectangle */
  1276. gdImageRectangle(im, 0, 0, 99, 99, black);
  1277. /* Open output file in binary mode */
  1278. out = fopen("rect.png", "wb");
  1279. /* Write PNG */
  1280. gdImagePng(im, out);
  1281. /* Close file */
  1282. fclose(out);
  1283. /* Destroy image */
  1284. gdImageDestroy(im);
  1285.  
  1286.    void* gdImagePngPtr(gdImagePtr im, int *size) _(FUNCTION)_
  1287.    Identical to gdImagePng except that it returns a pointer to a memory
  1288.    area with the PNG data. This memory must be freed by the caller when
  1289.    it is no longer needed. _The caller must invoke gdFree(), not free(),
  1290.    unless the caller is absolutely certain that the same implementations
  1291.    of malloc, free, etc. are used both at library build time and at
  1292.    application build time._ The 'size' parameter receives the total size
  1293.    of the block of memory.
  1294.    
  1295.    gdImagePngToSink(gdImagePtr im, gdSinkPtr out) _(FUNCTION)_
  1296.    gdImagePngToSink is called to write a PNG to a data "sink"
  1297.    (destination) other than a file. Usage is very similar to the
  1298.    gdImagePng function, except that the programmer provides a custom data
  1299.    sink.
  1300.    
  1301.    The programmer must write an output function which accepts a context
  1302.    pointer, a buffer, and a number of bytes to be written as arguments.
  1303.    This function must write the number of bytes requested and return that
  1304.    number, unless an error has occurred, in which case the function
  1305.    should return -1. The programmer then creates a gdSink structure and
  1306.    sets the sink pointer to the output function and the context pointer
  1307.    to any value which is useful to the programmer.
  1308.    
  1309.    The example below implements gdImagePng by creating a custom data
  1310.    source and invoking gdImagePngFromSink.
  1311.  
  1312. static int stdioSink(void *context, char *buffer, int len)
  1313. {
  1314.         return fwrite(buffer, 1, len, (FILE *) context);
  1315. }
  1316.  
  1317. void gdImagePng(gdImagePtr im, FILE *out)
  1318. {
  1319.         gdSink mySink;
  1320.         mySink.context = (void *) out;
  1321.         mySink.sink = stdioSink;
  1322.         gdImagePngToSink(im, &mySink);
  1323. }
  1324.  
  1325.    void gdImageWBMP(gdImagePtr im, int fg, FILE *out)
  1326.    gdImageWBMPCtx(gdIOCtx *out) _(FUNCTION)__(FUNCTION)_
  1327.    gdImageWBMP outputs the specified image to the specified file in WBMP
  1328.    format. The file must be open for writing. Under MSDOS and all
  1329.    versions of Windows, it is important to use "wb" as opposed to simply
  1330.    "w" as the mode when opening the file, and under Unix there is no
  1331.    penalty for doing so. gdImageWBMP does _not_ close the file; your code
  1332.    must do so.
  1333.    
  1334.    _WBMP file support is black and white only. The color index specified
  1335.    by the fg argument is the "foreground," and only pixels of this color
  1336.    will be set in the WBMP file._ All other pixels will be considered
  1337.    "background."
  1338.  
  1339. ... inside a function ...
  1340. gdImagePtr im;
  1341. int black, white;
  1342. FILE *out;
  1343. /* Create the image */
  1344. im = gdImageCreate(100, 100);
  1345. /* Allocate background */
  1346. white = gdImageColorAllocate(im, 255, 255, 255);
  1347. /* Allocate drawing color */
  1348. black = gdImageColorAllocate(im, 0, 0, 0);
  1349. /* Draw rectangle */
  1350. gdImageRectangle(im, 0, 0, 99, 99, black);
  1351. /* Open output file in binary mode */
  1352. out = fopen("rect.wbmp", "wb");
  1353. /* Write WBMP, with black as foreground */
  1354. gdImageWBMP(im, black, out);
  1355. /* Close file */
  1356. fclose(out);
  1357. /* Destroy image */
  1358. gdImageDestroy(im);
  1359.  
  1360.    void* gdImageWBMPPtr(gdImagePtr im, int *size) _(FUNCTION)_
  1361.    Identical to gdImageWBMP except that it returns a pointer to a memory
  1362.    area with the WBMP data. This memory must be freed by the caller when
  1363.    it is no longer needed. _The caller must invoke gdFree(), not free(),
  1364.    unless the caller is absolutely certain that the same implementations
  1365.    of malloc, free, etc. are used both at library build time and at
  1366.    application build time._ The 'size' parameter receives the total size
  1367.    of the block of memory.
  1368.    
  1369.    void gdImageGd(gdImagePtr im, FILE *out) _(FUNCTION)_
  1370.    gdImageGd outputs the specified image to the specified file in the gd
  1371.    image format. The file must be open for writing. Under MSDOS and all
  1372.    versions of Windows, it is important to use "wb" as opposed to simply
  1373.    "w" as the mode when opening the file, and under Unix there is no
  1374.    penalty for doing so. gdImagePng does _not_ close the file; your code
  1375.    must do so.
  1376.    
  1377.    The gd image format is intended for fast reads and writes of images
  1378.    your program will need frequently to build other images. It is _not_ a
  1379.    compressed format, and is not intended for general use.
  1380.  
  1381. ... inside a function ...
  1382. gdImagePtr im;
  1383. int black, white;
  1384. FILE *out;
  1385. /* Create the image */
  1386. im = gdImageCreate(100, 100);
  1387. /* Allocate background */
  1388. white = gdImageColorAllocate(im, 255, 255, 255);
  1389. /* Allocate drawing color */
  1390. black = gdImageColorAllocate(im, 0, 0, 0);
  1391. /* Draw rectangle */
  1392. gdImageRectangle(im, 0, 0, 99, 99, black);
  1393. /* Open output file in binary mode */
  1394. out = fopen("rect.gd", "wb");
  1395. /* Write gd format file */
  1396. gdImageGd(im, out);
  1397. /* Close file */
  1398. fclose(out);
  1399. /* Destroy image */
  1400. gdImageDestroy(im);
  1401.  
  1402.    void* gdImageGdPtr(gdImagePtr im, int *size) _(FUNCTION)_
  1403.    Identical to gdImageGd except that it returns a pointer to a memory
  1404.    area with the GD data. This memory must be freed by the caller when it
  1405.    is no longer needed. _The caller must invoke gdFree(), not free(),
  1406.    unless the caller is absolutely certain that the same implementations
  1407.    of malloc, free, etc. are used both at library build time and at
  1408.    application build time._ The 'size' parameter receives the total size
  1409.    of the block of memory.
  1410.    
  1411.    void gdImageGd2(gdImagePtr im, FILE *out, int chunkSize, int fmt)
  1412.    _(FUNCTION)_
  1413.    gdImageGd2 outputs the specified image to the specified file in the
  1414.    gd2 image format. The file must be open for writing. Under MSDOS and
  1415.    all versions of Windows, it is important to use "wb" as opposed to
  1416.    simply "w" as the mode when opening the file, and under Unix there is
  1417.    no penalty for doing so. gdImageGd2 does _not_ close the file; your
  1418.    code must do so.
  1419.    
  1420.    The gd2 image format is intended for fast reads and writes of parts of
  1421.    images. It is a compressed format, and well suited to retrieving smll
  1422.    sections of much larger images. The third and fourth parameters are
  1423.    the 'chunk size' and format resposectively.
  1424.    
  1425.    The file is stored as a series of compressed subimages, and the _Chunk
  1426.    Size_ determines the sub-image size - a value of zero causes the GD
  1427.    library to use the default.
  1428.    
  1429.    It is also possible to store GD2 files in an uncompressed format, in
  1430.    which case the fourth parameter should be GD2_FMT_RAW.
  1431.  
  1432. ... inside a function ...
  1433. gdImagePtr im;
  1434. int black, white;
  1435. FILE *out;
  1436. /* Create the image */
  1437. im = gdImageCreate(100, 100);
  1438. /* Allocate background */
  1439. white = gdImageColorAllocate(im, 255, 255, 255);
  1440. /* Allocate drawing color */
  1441. black = gdImageColorAllocate(im, 0, 0, 0);
  1442. /* Draw rectangle */
  1443. gdImageRectangle(im, 0, 0, 99, 99, black);
  1444. /* Open output file in binary mode */
  1445. out = fopen("rect.gd", "wb");
  1446. /* Write gd2 format file */
  1447. gdImageGd2(im, out, 0, GD2_FMT_COMPRESSED);
  1448. /* Close file */
  1449. fclose(out);
  1450. /* Destroy image */
  1451. gdImageDestroy(im);
  1452.  
  1453.    void* gdImageGd2Ptr(gdImagePtr im, int chunkSize, int fmt, int *size)
  1454.    _(FUNCTION)_
  1455.    Identical to gdImageGd2 except that it returns a pointer to a memory
  1456.    area with the GD2 data. This memory must be freed by the caller when
  1457.    it is no longer needed. _The caller must invoke gdFree(), not free(),
  1458.    unless the caller is absolutely certain that the same implementations
  1459.    of malloc, free, etc. are used both at library build time and at
  1460.    application build time._ The 'size' parameter receives the total size
  1461.    of the block of memory.
  1462.    
  1463.   Drawing Functions
  1464.   
  1465.    void gdImageSetPixel(gdImagePtr im, int x, int y, int color)
  1466.           _(FUNCTION)_
  1467.           gdImageSetPixel sets a pixel to a particular color index.
  1468.           Always use this function or one of the other drawing functions
  1469.           to access pixels; do not access the pixels of the gdImage
  1470.           structure directly.
  1471.           
  1472.  
  1473. ... inside a function ...
  1474. gdImagePtr im;
  1475. int black;
  1476. int white;
  1477. im = gdImageCreate(100, 100);
  1478. /* Background color (first allocated) */
  1479. black = gdImageColorAllocate(im, 0, 0, 0);
  1480. /* Allocate the color white (red, green and blue all maximum). */
  1481. white = gdImageColorAllocate(im, 255, 255, 255);
  1482. /* Set a pixel near the center. */
  1483. gdImageSetPixel(im, 50, 50, white);
  1484. /* ... Do something with the image, such as saving it to a file... */
  1485. /* Destroy it */
  1486. gdImageDestroy(im);
  1487.  
  1488.    void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int
  1489.           color) _(FUNCTION)_
  1490.           gdImageLine is used to draw a line between two endpoints (x1,y1
  1491.           and x2, y2). The line is drawn using the color index specified.
  1492.           Note that the color index can be an actual color returned by
  1493.           gdImageColorAllocate or one of gdStyled, gdBrushed or
  1494.           gdStyledBrushed.
  1495.           
  1496.  
  1497. ... inside a function ...
  1498. gdImagePtr im;
  1499. int black;
  1500. int white;
  1501. im = gdImageCreate(100, 100);
  1502. /* Background color (first allocated) */
  1503. black = gdImageColorAllocate(im, 0, 0, 0);
  1504. /* Allocate the color white (red, green and blue all maximum). */
  1505. white = gdImageColorAllocate(im, 255, 255, 255);
  1506. /* Draw a line from the upper left corner to the lower right corner. */
  1507. gdImageLine(im, 0, 0, 99, 99, white);
  1508. /* ... Do something with the image, such as saving it to a file... */
  1509. /* Destroy it */
  1510. gdImageDestroy(im);
  1511.  
  1512.    void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2,
  1513.           int color) _(FUNCTION)_
  1514.           gdImageDashedLine is provided _solely for backwards
  1515.           compatibility _with gd 1.0. New programs should draw dashed
  1516.           lines using the normal gdImageLine function and the new
  1517.           gdImageSetStyle function.
  1518.           
  1519.           gdImageDashedLine is used to draw a dashed line between two
  1520.           endpoints (x1,y1 and x2, y2). The line is drawn using the color
  1521.           index specified. The portions of the line that are not drawn
  1522.           are left transparent so the background is visible.
  1523.           
  1524.  
  1525. ... inside a function ...
  1526. gdImagePtr im;
  1527. int black;
  1528. int white;
  1529. im = gdImageCreate(100, 100);
  1530. /* Background color (first allocated) */
  1531. black = gdImageColorAllocate(im, 0, 0, 0);
  1532. /* Allocate the color white (red, green and blue all maximum). */
  1533. white = gdImageColorAllocate(im, 255, 255, 255);
  1534. /* Draw a dashed line from the upper left corner to the lower right corner. */
  1535. gdImageDashedLine(im, 0, 0, 99, 99);
  1536. /* ... Do something with the image, such as saving it to a file... */
  1537. /* Destroy it */
  1538. gdImageDestroy(im);
  1539.  
  1540.    void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal,
  1541.           int color) _(FUNCTION)_
  1542.           gdImagePolygon is used to draw a polygon with the verticies (at
  1543.           least 3) specified, using the color index specified. See also
  1544.           gdImageFilledPolygon.
  1545.           
  1546.  
  1547. ... inside a function ...
  1548. gdImagePtr im;
  1549. int black;
  1550. int white;
  1551. /* Points of polygon */
  1552. gdPoint points[3];
  1553. im = gdImageCreate(100, 100);
  1554. /* Background color (first allocated) */
  1555. black = gdImageColorAllocate(im, 0, 0, 0);
  1556. /* Allocate the color white (red, green and blue all maximum). */
  1557. white = gdImageColorAllocate(im, 255, 255, 255);
  1558. /* Draw a triangle. */
  1559. points[0].x = 50;
  1560. points[0].y = 0;
  1561. points[1].x = 99;
  1562. points[1].y = 99;
  1563. points[2].x = 0;
  1564. points[2].y = 99;
  1565. gdImagePolygon(im, points, 3, white);
  1566. /* ... Do something with the image, such as saving it to a file... */
  1567. /* Destroy it */
  1568. gdImageDestroy(im);
  1569.  
  1570.    void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2,
  1571.           int color) _(FUNCTION)_
  1572.           gdImageRectangle is used to draw a rectangle with the two
  1573.           corners (upper left first, then lower right) specified, using
  1574.           the color index specified.
  1575.           
  1576.  
  1577. ... inside a function ...
  1578. gdImagePtr im;
  1579. int black;
  1580. int white;
  1581. im = gdImageCreate(100, 100);
  1582. /* Background color (first allocated) */
  1583. black = gdImageColorAllocate(im, 0, 0, 0);
  1584. /* Allocate the color white (red, green and blue all maximum). */
  1585. white = gdImageColorAllocate(im, 255, 255, 255);
  1586. /* Draw a rectangle occupying the central area. */
  1587. gdImageRectangle(im, 25, 25, 74, 74, white);
  1588. /* ... Do something with the image, such as saving it to a file... */
  1589. /* Destroy it */
  1590. gdImageDestroy(im);
  1591.  
  1592.    void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int
  1593.           pointsTotal, int color) _(FUNCTION)_
  1594.           gdImageFilledPolygon is used to fill a polygon with the
  1595.           verticies (at least 3) specified, using the color index
  1596.           specified. See also gdImagePolygon.
  1597.           
  1598.  
  1599. ... inside a function ...
  1600. gdImagePtr im;
  1601. int black;
  1602. int white;
  1603. int red;
  1604. /* Points of polygon */
  1605. gdPoint points[3];
  1606. im = gdImageCreate(100, 100);
  1607. /* Background color (first allocated) */
  1608. black = gdImageColorAllocate(im, 0, 0, 0);
  1609. /* Allocate the color white (red, green and blue all maximum). */
  1610. white = gdImageColorAllocate(im, 255, 255, 255);
  1611. /* Allocate the color red. */
  1612. red = gdImageColorAllocate(im, 255, 0, 0);
  1613. /* Draw a triangle. */
  1614. points[0].x = 50;
  1615. points[0].y = 0;
  1616. points[1].x = 99;
  1617. points[1].y = 99;
  1618. points[2].x = 0;
  1619. points[2].y = 99;
  1620. /* Paint it in white */
  1621. gdImageFilledPolygon(im, points, 3, white);
  1622. /* Outline it in red; must be done second */
  1623. gdImagePolygon(im, points, 3, red);
  1624. /* ... Do something with the image, such as saving it to a file... */
  1625. /* Destroy it */
  1626. gdImageDestroy(im);
  1627.  
  1628.    void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int
  1629.           y2, int color) _(FUNCTION)_
  1630.           gdImageFilledRectangle is used to draw a solid rectangle with
  1631.           the two corners (upper left first, then lower right) specified,
  1632.           using the color index specified.
  1633.           
  1634.  
  1635. ... inside a function ...
  1636. gdImagePtr im;
  1637. int black;
  1638. int white;
  1639. im = gdImageCreate(100, 100);
  1640. /* Background color (first allocated) */
  1641. black = gdImageColorAllocate(im, 0, 0, 0);
  1642. /* Allocate the color white (red, green and blue all maximum). */
  1643. white = int gdImageColorAllocate(im, 255, 255, 255);
  1644. /* Draw a filled rectangle occupying the central area. */
  1645. gdImageFilledRectangle(im, 25, 25, 74, 74, white);
  1646. /* ... Do something with the image, such as saving it to a file... */
  1647. /* Destroy it */
  1648. gdImageDestroy(im);
  1649.  
  1650.    void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s,
  1651.           int e, int color) _(FUNCTION)_
  1652.           gdImageArc is used to draw a partial ellipse centered at the
  1653.           given point, with the specified width and height in pixels. The
  1654.           arc begins at the position in degrees specified by s and ends
  1655.           at the position specified by e. The arc is drawn in the color
  1656.           specified by the last argument. A circle can be drawn by
  1657.           beginning from 0 degrees and ending at 360 degrees, with width
  1658.           and height being equal. e must be greater than s. Values
  1659.           greater than 360 are interpreted modulo 360.
  1660.           
  1661.  
  1662. ... inside a function ...
  1663. gdImagePtr im;
  1664. int black;
  1665. int white;
  1666. im = gdImageCreate(100, 50);
  1667. /* Background color (first allocated) */
  1668. black = gdImageColorAllocate(im, 0, 0, 0);
  1669. /* Allocate the color white (red, green and blue all maximum). */
  1670. white = gdImageColorAllocate(im, 255, 255, 255);
  1671. /* Inscribe an ellipse in the image. */
  1672. gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
  1673. /* ... Do something with the image, such as saving it to a file... */
  1674. /* Destroy it */
  1675. gdImageDestroy(im);
  1676.  
  1677.    void gdImageFilledArc(gdImagePtr im, int cx, int cy, int w, int h, int
  1678.           s, int e, int color, int style) _(FUNCTION)_
  1679.           gdImageFilledArc is used to draw a partial ellipse centered at
  1680.           the given point, with the specified width and height in pixels.
  1681.           The arc begins at the position in degrees specified by s and
  1682.           ends at the position specified by e. The arc is filled in the
  1683.           color specified by the second to last argument. A circle can be
  1684.           drawn by beginning from 0 degrees and ending at 360 degrees,
  1685.           with width and height being equal. e must be greater than s.
  1686.           Values greater than 360 are interpreted modulo 360. The last
  1687.           argument is a bitwise OR of the following possibilities:
  1688.           
  1689.           + gdArc
  1690.           + gdChord
  1691.           + gdPie (synonym for gdChord)
  1692.           + gdNoFill
  1693.           + gdEdged
  1694.             
  1695.           gdArc and gdChord are mutually exclusive; gdChord just connects
  1696.           the starting and ending angles with a straight line, while
  1697.           gdArc produces a rounded edge. gdPie is a synonym for gdArc.
  1698.           gdNoFill indicates that the arc or chord should be outlined,
  1699.           not filled. gdEdged, used together with gdNoFill, indicates
  1700.           that the beginning and ending angles should be connected to the
  1701.           center; this is a good way to outline (rather than fill) a 'pie
  1702.           slice'.
  1703.           
  1704.  
  1705. ... inside a function ...
  1706. gdImagePtr im;
  1707. int black;
  1708. int white;
  1709. im = gdImageCreate(100, 50);
  1710. /* Background color (first allocated) */
  1711. black = gdImageColorAllocate(im, 0, 0, 0);
  1712. /* Allocate the color white (red, green and blue all maximum). */
  1713. white = gdImageColorAllocate(im, 255, 255, 255);
  1714. /* Inscribe a filled pie slice in the image. */
  1715. gdImageFilledArc(im, 50, 25, 98, 48, 0, 45, white, gdArc);
  1716. /* ... Do something with the image, such as saving it to a file... */
  1717. /* Destroy it */
  1718. gdImageDestroy(im);
  1719.  
  1720.    void gdImageFilledEllipse(gdImagePtr im, int cx, int cy, int w, int h,
  1721.           int s, int e, int color) _(FUNCTION)_
  1722.           gdImageFilledEllipse is used to draw an ellipse centered at the
  1723.           given point, with the specified width and height in pixels. The
  1724.           ellipse is filled in the color specified by the last argument.
  1725.           A circle can be drawn by beginning from 0 degrees and ending at
  1726.           360 degrees, with width and height being equal. e must be
  1727.           greater than s. Values greater than 360 are interpreted modulo
  1728.           360.
  1729.           
  1730.  
  1731. ... inside a function ...
  1732. gdImagePtr im;
  1733. int black;
  1734. int white;
  1735. im = gdImageCreate(100, 50);
  1736. /* Background color (first allocated) */
  1737. black = gdImageColorAllocate(im, 0, 0, 0);
  1738. /* Allocate the color white (red, green and blue all maximum). */
  1739. white = gdImageColorAllocate(im, 255, 255, 255);
  1740. /* Inscribe a filled ellipse in the image. */
  1741. gdImageFilledEllipse(im, 50, 25, 98, 48, white);
  1742. /* ... Do something with the image, such as saving it to a file... */
  1743. /* Destroy it */
  1744. gdImageDestroy(im);
  1745.  
  1746.    void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int
  1747.           color) _(FUNCTION)_
  1748.           gdImageFillToBorder floods a portion of the image with the
  1749.           specified color, beginning at the specified point and stopping
  1750.           at the specified border color. For a way of flooding an area
  1751.           defined by the color of the starting point, see gdImageFill.
  1752.           
  1753.           The border color _cannot_ be a special color such as gdTiled;
  1754.           it must be a proper solid color. The fill color can be,
  1755.           however.
  1756.           
  1757.           Note that gdImageFillToBorder is recursive. It is not the most
  1758.           naive implementation possible, and the implementation is
  1759.           expected to improve, but there will always be degenerate cases
  1760.           in which the stack can become very deep. This can be a problem
  1761.           in MSDOS and MS Windows 3.1 environments. (Of course, in a Unix
  1762.           or Windows 95/98/NT environment with a proper stack, this is
  1763.           not a problem at all.)
  1764.           
  1765.  
  1766. ... inside a function ...
  1767. gdImagePtr im;
  1768. int black;
  1769. int white;
  1770. int red;
  1771. im = gdImageCreate(100, 50);
  1772. /* Background color (first allocated) */
  1773. black = gdImageColorAllocate(im, 0, 0, 0);
  1774. /* Allocate the color white (red, green and blue all maximum). */
  1775. white = gdImageColorAllocate(im, 255, 255, 255);
  1776. /* Allocate the color red. */
  1777. red = gdImageColorAllocate(im, 255, 0, 0);
  1778. /* Inscribe an ellipse in the image. */
  1779. gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
  1780. /* Flood-fill the ellipse. Fill color is red, border color is
  1781.         white (ellipse). */
  1782. gdImageFillToBorder(im, 50, 50, white, red);
  1783. /* ... Do something with the image, such as saving it to a file... */
  1784. /* Destroy it */
  1785. gdImageDestroy(im);
  1786.  
  1787.    void gdImageFill(gdImagePtr im, int x, int y, int color) _(FUNCTION)_
  1788.           gdImageFill floods a portion of the image with the specified
  1789.           color, beginning at the specified point and flooding the
  1790.           surrounding region of the same color as the starting point. For
  1791.           a way of flooding a region defined by a specific border color
  1792.           rather than by its interior color, see gdImageFillToBorder.
  1793.           
  1794.           The fill color can be gdTiled, resulting in a tile fill using
  1795.           another image as the tile. However, the tile image cannot be
  1796.           transparent. If the image you wish to fill with has a
  1797.           transparent color index, call gdImageTransparent on the tile
  1798.           image and set the transparent color index to -1 to turn off its
  1799.           transparency.
  1800.           
  1801.           Note that gdImageFill is recursive. It is not the most naive
  1802.           implementation possible, and the implementation is expected to
  1803.           improve, but there will always be degenerate cases in which the
  1804.           stack can become very deep. This can be a problem in MSDOS and
  1805.           MS Windows environments. (Of course, in a Unix or Windows
  1806.           95/98/NT environment with a proper stack, this is not a problem
  1807.           at all.)
  1808.           
  1809.  
  1810. ... inside a function ...
  1811. gdImagePtr im;
  1812. int black;
  1813. int white;
  1814. int red;
  1815. im = gdImageCreate(100, 50);
  1816. /* Background color (first allocated) */
  1817. black = gdImageColorAllocate(im, 0, 0, 0);
  1818. /* Allocate the color white (red, green and blue all maximum). */
  1819. white = gdImageColorAllocate(im, 255, 255, 255);
  1820. /* Allocate the color red. */
  1821. red = gdImageColorAllocate(im, 255, 0, 0);
  1822. /* Inscribe an ellipse in the image. */
  1823. gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
  1824. /* Flood-fill the ellipse. Fill color is red, and will replace the
  1825.         black interior of the ellipse. */
  1826. gdImageFill(im, 50, 50, red);
  1827. /* ... Do something with the image, such as saving it to a file... */
  1828. /* Destroy it */
  1829. gdImageDestroy(im);
  1830.  
  1831.    void gdImageSetBrush(gdImagePtr im, gdImagePtr brush) _(FUNCTION)_
  1832.           A "brush" is an image used to draw wide, shaped strokes in
  1833.           another image. Just as a paintbrush is not a single point, a
  1834.           brush image need not be a single pixel. _Any_ gd image can be
  1835.           used as a brush, and by setting the transparent color index of
  1836.           the brush image with gdImageColorTransparent, a brush of any
  1837.           shape can be created. All line-drawing functions, such as
  1838.           gdImageLine and gdImagePolygon, will use the current brush if
  1839.           the special "color" gdBrushed or gdStyledBrushed is used when
  1840.           calling them.
  1841.           
  1842.           gdImageSetBrush is used to specify the brush to be used in a
  1843.           particular image. You can set any image to be the brush. If the
  1844.           brush image does not have the same color map as the first
  1845.           image, any colors missing from the first image will be
  1846.           allocated. If not enough colors can be allocated, the closest
  1847.           colors already available will be used. This allows arbitrary
  1848.           PNGs to be used as brush images. It also means, however, that
  1849.           you should not set a brush unless you will actually use it; if
  1850.           you set a rapid succession of different brush images, you can
  1851.           quickly fill your color map, and the results will not be
  1852.           optimal.
  1853.           
  1854.           You need not take any special action when you are finished with
  1855.           a brush. As for any other image, if you will not be using the
  1856.           brush image for any further purpose, you should call
  1857.           gdImageDestroy. You must not use the color gdBrushed if the
  1858.           current brush has been destroyed; you can of course set a new
  1859.           brush to replace it.
  1860.           
  1861.  
  1862. ... inside a function ...
  1863. gdImagePtr im, brush;
  1864. FILE *in;
  1865. int black;
  1866. im = gdImageCreate(100, 100);
  1867. /* Open the brush PNG. For best results, portions of the
  1868.         brush that should be transparent (ie, not part of the
  1869.         brush shape) should have the transparent color index. */
  1870. in = fopen("star.png", "rb");
  1871. brush = gdImageCreateFromPng(in);
  1872. /* Background color (first allocated) */
  1873. black = gdImageColorAllocate(im, 0, 0, 0);
  1874. gdImageSetBrush(im, brush);
  1875. /* Draw a line from the upper left corner to the lower right corner
  1876.         using the brush. */
  1877. gdImageLine(im, 0, 0, 99, 99, gdBrushed);
  1878. /* ... Do something with the image, such as saving it to a file... */
  1879. /* Destroy it */
  1880. gdImageDestroy(im);
  1881. /* Destroy the brush image */
  1882. gdImageDestroy(brush);
  1883.  
  1884.    void gdImageSetTile(gdImagePtr im, gdImagePtr tile) _(FUNCTION)_
  1885.           A "tile" is an image used to fill an area with a repeated
  1886.           pattern. _Any_ gd image can be used as a tile, and by setting
  1887.           the transparent color index of the tile image with
  1888.           gdImageColorTransparent, a tile that allows certain parts of
  1889.           the underlying area to shine through can be created. All
  1890.           region-filling functions, such as gdImageFill and
  1891.           gdImageFilledPolygon, will use the current tile if the special
  1892.           "color" gdTiled is used when calling them.
  1893.           
  1894.           gdImageSetTile is used to specify the tile to be used in a
  1895.           particular image. You can set any image to be the tile. If the
  1896.           tile image does not have the same color map as the first image,
  1897.           any colors missing from the first image will be allocated. If
  1898.           not enough colors can be allocated, the closest colors already
  1899.           available will be used. This allows arbitrary PNGs to be used
  1900.           as tile images. It also means, however, that you should not set
  1901.           a tile unless you will actually use it; if you set a rapid
  1902.           succession of different tile images, you can quickly fill your
  1903.           color map, and the results will not be optimal.
  1904.           
  1905.           You need not take any special action when you are finished with
  1906.           a tile. As for any other image, if you will not be using the
  1907.           tile image for any further purpose, you should call
  1908.           gdImageDestroy. You must not use the color gdTiled if the
  1909.           current tile has been destroyed; you can of course set a new
  1910.           tile to replace it.
  1911.           
  1912.  
  1913. ... inside a function ...
  1914. gdImagePtr im, tile;
  1915. FILE *in;
  1916. int black;
  1917. im = gdImageCreate(100, 100);
  1918. /* Open the tile PNG. For best results, portions of the
  1919.         tile that should be transparent (ie, allowing the
  1920.         background to shine through) should have the transparent
  1921.         color index. */
  1922. in = fopen("star.png", "rb");
  1923. tile = gdImageCreateFromPng(in);
  1924. /* Background color (first allocated) */
  1925. black = gdImageColorAllocate(im, 0, 0, 0);
  1926. gdImageSetTile(im, tile);
  1927. /* Fill an area using the tile. */
  1928. gdImageFilledRectangle(im, 25, 25, 75, 75, gdTiled);
  1929. /* ... Do something with the image, such as saving it to a file... */
  1930. /* Destroy it */
  1931. gdImageDestroy(im);
  1932. /* Destroy the tile image */
  1933. gdImageDestroy(tile);
  1934.  
  1935.    void gdImageSetStyle(gdImagePtr im, int *style, int styleLength)
  1936.           _(FUNCTION)_
  1937.           It is often desirable to draw dashed lines, dotted lines, and
  1938.           other variations on a broken line. gdImageSetStyle can be used
  1939.           to set any desired series of colors, including a special color
  1940.           that leaves the background intact, to be repeated during the
  1941.           drawing of a line.
  1942.           
  1943.           To use gdImageSetStyle, create an array of integers and assign
  1944.           them the desired series of color values to be repeated. You can
  1945.           assign the special color value gdTransparent to indicate that
  1946.           the existing color should be left unchanged for that particular
  1947.           pixel (allowing a dashed line to be attractively drawn over an
  1948.           existing image).
  1949.           
  1950.           Then, to draw a line using the style, use the normal
  1951.           gdImageLine function with the special color value gdStyled.
  1952.           
  1953.           As of version 1.1.1, the style array is copied when you set the
  1954.           style, so you need not be concerned with keeping the array
  1955.           around indefinitely. This should not break existing code that
  1956.           assumes styles are not copied.
  1957.           
  1958.           You can also combine styles and brushes to draw the brush image
  1959.           at intervals instead of in a continuous stroke. When creating a
  1960.           style for use with a brush, the style values are interpreted
  1961.           differently: zero (0) indicates pixels at which the brush
  1962.           should not be drawn, while one (1) indicates pixels at which
  1963.           the brush should be drawn. To draw a styled, brushed line, you
  1964.           must use the special color value gdStyledBrushed. For an
  1965.           example of this feature in use, see gddemo.c (provided in the
  1966.           distribution).
  1967.           
  1968.  
  1969. gdImagePtr im;
  1970. int styleDotted[2], styleDashed[6];
  1971. FILE *in;
  1972. int black;
  1973. int red;
  1974. im = gdImageCreate(100, 100);
  1975. /* Background color (first allocated) */
  1976. black = gdImageColorAllocate(im, 0, 0, 0);
  1977. red = gdImageColorAllocate(im, 255, 0, 0);
  1978. /* Set up dotted style. Leave every other pixel alone. */
  1979. styleDotted[0] = red;
  1980. styleDotted[1] = gdTransparent;
  1981. /* Set up dashed style. Three on, three off. */
  1982. styleDashed[0] = red;
  1983. styleDashed[1] = red;
  1984. styleDashed[2] = red;
  1985. styleDashed[3] = gdTransparent;
  1986. styleDashed[4] = gdTransparent;
  1987. styleDashed[5] = gdTransparent;
  1988. /* Set dotted style. Note that we have to specify how many pixels are
  1989.         in the style! */
  1990. gdImageSetStyle(im, styleDotted, 2);
  1991. /* Draw a line from the upper left corner to the lower right corner. */
  1992. gdImageLine(im, 0, 0, 99, 99, gdStyled);
  1993. /* Now the dashed line. */
  1994. gdImageSetStyle(im, styleDashed, 6);
  1995. gdImageLine(im, 0, 99, 0, 99, gdStyled);
  1996.  
  1997. /* ... Do something with the image, such as saving it to a file ... */
  1998.  
  1999. /* Destroy it */
  2000. gdImageDestroy(im);
  2001.  
  2002.    void gdImageAlphaBlending(gdImagePtr im, int blending) _(FUNCTION)_
  2003.           The gdImageAlphaBlending function allows for two different
  2004.           modes of drawing on truecolor images. In blending mode, the
  2005.           alpha channel component of the color supplied to all drawing
  2006.           functions, such as gdImageSetPixel, determines how much of the
  2007.           underlying color should be allowed to shine through. As a
  2008.           result, gd automatically blends the existing color at that
  2009.           point with the drawing color, and stores the result in the
  2010.           image. The resulting pixel is opaque. In non-blending mode, the
  2011.           drawing color is copied literally with its alpha channel
  2012.           information, replacing the destination pixel. Blending mode is
  2013.           not available when drawing on palette images.
  2014.           
  2015.  
  2016. gdImagePtr im;
  2017. int red, blue;
  2018. im = gdImageCreateTrueColor(100, 100);
  2019. /* Background color */
  2020. red = gdTrueColor(255, 0, 0);
  2021. gdImageFilledRectangle(im, 0, 0, 100, 100, red);
  2022. /* Drawing color. Full transparency would be an alpha channel value
  2023.         of 127 (gd has a 7 bit alpha chnanel). 0 is opaque,
  2024.         127 is transparent. So cut gdAlphaTransparent in half to get
  2025.         50% blending. */
  2026. blue = gdTrueColorAlpha(0, 0, 255, gdAlphaTransparent / 2);
  2027. /* Draw with blending. Result will be 50% red, 50% blue: yellow
  2028.         (emitted light, remember, not reflected light. What you learned
  2029.         in Kindergarten is wrong here). */
  2030. gdImageAlphaBlending(im, 1);
  2031. gdImageFilledRectangle(im, 0, 0, 25, 25, blue);
  2032. /* Draw without blending. Result will be 50% blue, 50%
  2033.         the background color of the image viewer or web browser
  2034.         used; results in browsers that don't support
  2035.         semi-transparent pixels are unpredictable! */
  2036. gdImageAlphaBlending(im, 0);
  2037. gdImageFilledRectangle(im, 75, 75, 25, 25, blue);
  2038. /* Write the image to disk, etc. */
  2039.  
  2040.   Query Functions
  2041.   
  2042.         int gdImageAlpha(gdImagePtr im, int color) _(MACRO)_
  2043.                 gdImageAlpha is a macro which returns the alpha channel
  2044.                 component of the specified color index. Alpha channel
  2045.                 values vary between 0 (gdAlphaOpaque), which does not
  2046.                 blend at all with the background, through 127
  2047.                 (gdAlphaTransparent), which allows the background to
  2048.                 shine through 100%. Use this macro rather than accessing
  2049.                 the structure members directly. int
  2050.                 gdImageBlue(gdImagePtr im, int color)
  2051.                 
  2052.           _(MACRO)_
  2053.           gdImageBlue is a macro which returns the blue component of the
  2054.           specified color index. Use this macro rather than accessing the
  2055.           structure members directly.
  2056.           
  2057.    int gdImageGetPixel(gdImagePtr im, int x, int y) _(FUNCTION)_
  2058.           gdImageGetPixel() retrieves the color index of a particular
  2059.           pixel. Always use this function to query pixels; do not access
  2060.           the pixels of the gdImage structure directly.
  2061.           
  2062.  
  2063. ... inside a function ...
  2064. FILE *in;
  2065. gdImagePtr im;
  2066. int c;
  2067. in = fopen("mypng.png", "rb");
  2068. im = gdImageCreateFromPng(in);
  2069. fclose(in);
  2070. c = gdImageGetPixel(im, gdImageSX(im) / 2, gdImageSY(im) / 2);
  2071. printf("The value of the center pixel is %d; RGB values are %d,%d,%d\n",
  2072.         c, im->red[c], im->green[c], im->blue[c]);
  2073. gdImageDestroy(im);
  2074.  
  2075.    int gdImageBoundsSafe(gdImagePtr im, int x, int y) _(FUNCTION)_
  2076.           gdImageBoundsSafe returns true (1) if the specified point is
  2077.           within the bounds of the image, false (0) if not. This function
  2078.           is intended primarily for use by those who wish to add
  2079.           functions to gd. All of the gd drawing functions already clip
  2080.           safely to the edges of the image.
  2081.           
  2082.  
  2083. ... inside a function ...
  2084. gdImagePtr im;
  2085. int black;
  2086. int white;
  2087. im = gdImageCreate(100, 100);
  2088. if (gdImageBoundsSafe(im, 50, 50)) {
  2089.         printf("50, 50 is within the image bounds\n");
  2090. } else {
  2091.         printf("50, 50 is outside the image bounds\n");
  2092. }
  2093. gdImageDestroy(im);
  2094.  
  2095.    int gdImageGreen(gdImagePtr im, int color) _(MACRO)_
  2096.           gdImageGreen is a macro which returns the green component of
  2097.           the specified color index. Use this macro rather than accessing
  2098.           the structure members directly.
  2099.           
  2100.    int gdImageRed(gdImagePtr im, int color) _(MACRO)_
  2101.           gdImageRed is a macro which returns the red component of the
  2102.           specified color index. Use this macro rather than accessing the
  2103.           structure members directly.
  2104.           
  2105.    int gdImageSX(gdImagePtr im) _(MACRO)_
  2106.           gdImageSX is a macro which returns the width of the image in
  2107.           pixels. Use this macro rather than accessing the structure
  2108.           members directly.
  2109.           
  2110.    int gdImageSY(gdImagePtr im) _(MACRO)_
  2111.           gdImageSY is a macro which returns the height of the image in
  2112.           pixels. Use this macro rather than accessing the structure
  2113.           members directly.
  2114.           
  2115.   Fonts and text-handling functions
  2116.   
  2117.         void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y, int
  2118.                 c, int color) _(FUNCTION)_
  2119.                 gdImageChar is used to draw single characters on the
  2120.                 image. (To draw multiple characters, use gdImageString or
  2121.                 gdImageString16. See also gdImageStringFT for a high
  2122.                 quality solution.) The second argument is a pointer to a
  2123.                 font definition structure; five fonts are provided with
  2124.                 gd, gdFontTiny, gdFontSmall, gdFontMediumBold,
  2125.                 gdFontLarge, and gdFontGiant. You must include the files
  2126.                 "gdfontt.h", "gdfonts.h", "gdfontmb.h", "gdfontl.h" and
  2127.                 "gdfontg.h" respectively and (if you are not using a
  2128.                 library-based approach) link with the corresponding .c
  2129.                 files to use the provided fonts. The character specified
  2130.                 by the fifth argument is drawn from left to right in the
  2131.                 specified color. (See gdImageCharUp for a way of drawing
  2132.                 vertical text.) Pixels not set by a particular character
  2133.                 retain their previous color.
  2134.                 
  2135.  
  2136. #include "gd.h"
  2137. #include "gdfontl.h"
  2138. ... inside a function ...
  2139. gdImagePtr im;
  2140. int black;
  2141. int white;
  2142. im = gdImageCreate(100, 100);
  2143. /* Background color (first allocated) */
  2144. black = gdImageColorAllocate(im, 0, 0, 0);
  2145. /* Allocate the color white (red, green and blue all maximum). */
  2146. white = gdImageColorAllocate(im, 255, 255, 255);
  2147. /* Draw a character. */
  2148. gdImageChar(im, gdFontLarge, 0, 0, 'Q', white);
  2149. /* ... Do something with the image, such as saving it to a file... */
  2150. /* Destroy it */
  2151. gdImageDestroy(im);
  2152.  
  2153.         void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y,
  2154.                 int c, int color) _(FUNCTION)_
  2155.                 gdImageCharUp is used to draw single characters on the
  2156.                 image, rotated 90 degrees. (To draw multiple characters,
  2157.                 use gdImageStringUp or gdImageStringUp16.) The second
  2158.                 argument is a pointer to a font definition structure;
  2159.                 five fonts are provided with gd, gdFontTiny, gdFontSmall,
  2160.                 gdFontMediumBold, gdFontLarge, and gdFontGiant. You must
  2161.                 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
  2162.                 "gdfontl.h" and "gdfontg.h" respectively and (if you are
  2163.                 not using a library-based approach) link with the
  2164.                 corresponding .c files to use the provided fonts. The
  2165.                 character specified by the fifth argument is drawn from
  2166.                 bottom to top, rotated at a 90-degree angle, in the
  2167.                 specified color. (See gdImageChar for a way of drawing
  2168.                 horizontal text.) Pixels not set by a particular
  2169.                 character retain their previous color.
  2170.                 
  2171.  
  2172. #include "gd.h"
  2173. #include "gdfontl.h"
  2174. ... inside a function ...
  2175. gdImagePtr im;
  2176. int black;
  2177. int white;
  2178. im = gdImageCreate(100, 100);
  2179. /* Background color (first allocated) */
  2180. black = gdImageColorAllocate(im, 0, 0, 0);
  2181. /* Allocate the color white (red, green and blue all maximum). */
  2182. white = gdImageColorAllocate(im, 255, 255, 255);
  2183. /* Draw a character upwards so it rests against the top of the image. */
  2184. gdImageCharUp(im, gdFontLarge,
  2185.         0, gdFontLarge->h, 'Q', white);
  2186. /* ... Do something with the image, such as saving it to a file... */
  2187. /* Destroy it */
  2188. gdImageDestroy(im);
  2189.  
  2190.         void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y,
  2191.                 unsigned char *s, int color) _(FUNCTION)_
  2192.                 gdImageString is used to draw multiple characters on the
  2193.                 image. (To draw single characters, use gdImageChar.) The
  2194.                 second argument is a pointer to a font definition
  2195.                 structure; five fonts are provided with gd, gdFontTiny,
  2196.                 gdFontSmall, gdFontMediumBold, gdFontLarge, and
  2197.                 gdFontGiant. You must include the files "gdfontt.h",
  2198.                 "gdfonts.h", "gdfontmb.h", "gdfontl.h" and "gdfontg.h"
  2199.                 respectively and (if you are not using a library-based
  2200.                 approach) link with the corresponding .c files to use the
  2201.                 provided fonts. The null-terminated C string specified by
  2202.                 the fifth argument is drawn from left to right in the
  2203.                 specified color. (See gdImageStringUp for a way of
  2204.                 drawing vertical text. See also gdImageStringFT for a
  2205.                 high quality solution.) Pixels not set by a particular
  2206.                 character retain their previous color.
  2207.                 
  2208.  
  2209. #include "gd.h"
  2210. #include "gdfontl.h"
  2211. #include <string.h>
  2212. ... inside a function ...
  2213. gdImagePtr im;
  2214. int black;
  2215. int white;
  2216. /* String to draw. */
  2217. char *s = "Hello.";
  2218. im = gdImageCreate(100, 100);
  2219. /* Background color (first allocated) */
  2220. black = gdImageColorAllocate(im, 0, 0, 0);
  2221. /* Allocate the color white (red, green and blue all maximum). */
  2222. white = gdImageColorAllocate(im, 255, 255, 255);
  2223. /* Draw a centered string. */
  2224. gdImageString(im, gdFontLarge,
  2225.         im->w / 2 - (strlen(s) * gdFontLarge->w / 2),
  2226.         im->h / 2 - gdFontLarge->h / 2,
  2227.         s, white);
  2228. /* ... Do something with the image, such as saving it to a file... */
  2229. /* Destroy it */
  2230. gdImageDestroy(im);
  2231.  
  2232.         void gdImageString16(gdImagePtr im, gdFontPtr font, int x, int y,
  2233.                 unsigned short *s, int color) _(FUNCTION)_
  2234.                 gdImageString is used to draw multiple 16-bit characters
  2235.                 on the image. (To draw single characters, use
  2236.                 gdImageChar.) The second argument is a pointer to a font
  2237.                 definition structure; five fonts are provided with gd,
  2238.                 gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge,
  2239.                 and gdFontGiant. You must include the files "gdfontt.h",
  2240.                 "gdfonts.h", "gdfontmb.h", "gdfontl.h" and "gdfontg.h"
  2241.                 respectively and (if you are not using a library-based
  2242.                 approach) link with the corresponding .c files to use the
  2243.                 provided fonts. The null-terminated string of characters
  2244.                 represented as 16-bit unsigned short integers specified
  2245.                 by the fifth argument is drawn from left to right in the
  2246.                 specified color. (See gdImageStringUp16 for a way of
  2247.                 drawing vertical text.) Pixels not set by a particular
  2248.                 character retain their previous color.
  2249.                 
  2250.                 This function was added in gd1.3 to provide a means of
  2251.                 rendering fonts with more than 256 characters for those
  2252.                 who have them. A more frequently used routine is
  2253.                 gdImageString.
  2254.                 
  2255.         void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y,
  2256.                 unsigned char *s, int color) _(FUNCTION)_
  2257.                 gdImageStringUp is used to draw multiple characters on
  2258.                 the image, rotated 90 degrees. (To draw single
  2259.                 characters, use gdImageCharUp.) The second argument is a
  2260.                 pointer to a font definition structure; five fonts are
  2261.                 provided with gd, gdFontTiny, gdFontSmall,
  2262.                 gdFontMediumBold, gdFontLarge, and gdFontGiant. You must
  2263.                 include the files "gdfontt.h", "gdfonts.h", "gdfontmb.h",
  2264.                 "gdfontl.h" and "gdfontg.h" respectively and (if you are
  2265.                 not using a library-based approach) link with the
  2266.                 corresponding .c files to use the provided fonts.The
  2267.                 null-terminated C string specified by the fifth argument
  2268.                 is drawn from bottom to top (rotated 90 degrees) in the
  2269.                 specified color. (See gdImageString for a way of drawing
  2270.                 horizontal text.) Pixels not set by a particular
  2271.                 character retain their previous color.
  2272.                 
  2273.  
  2274. #include "gd.h"
  2275. #include "gdfontl.h"
  2276. #include <string.h>
  2277. ... inside a function ...
  2278. gdImagePtr im;
  2279. int black;
  2280. int white;
  2281. /* String to draw. */
  2282. char *s = "Hello.";
  2283. im = gdImageCreate(100, 100);
  2284. /* Background color (first allocated) */
  2285. black = gdImageColorAllocate(im, 0, 0, 0);
  2286. /* Allocate the color white (red, green and blue all maximum). */
  2287. white = gdImageColorAllocate(im, 255, 255, 255);
  2288. /* Draw a centered string going upwards. Axes are reversed,
  2289.         and Y axis is decreasing as the string is drawn. */
  2290. gdImageStringUp(im, gdFontLarge,
  2291.         im->w / 2 - gdFontLarge->h / 2,
  2292.         im->h / 2 + (strlen(s) * gdFontLarge->w / 2),
  2293.         s, white);
  2294. /* ... Do something with the image, such as saving it to a file... */
  2295. /* Destroy it */
  2296. gdImageDestroy(im);
  2297.  
  2298.         void gdImageStringUp16(gdImagePtr im, gdFontPtr font, int x, int
  2299.                 y, unsigned short *s, int color) _(FUNCTION)_
  2300.                 gdImageString is used to draw multiple 16-bit characters
  2301.                 vertically on the image. (To draw single characters, use
  2302.                 gdImageChar.) The second argument is a pointer to a font
  2303.                 definition structure; five fonts are provided with gd,
  2304.                 gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge,
  2305.                 and gdFontGiant. You must include the files "gdfontt.h",
  2306.                 "gdfonts.h", "gdfontmb.h", "gdfontl.h" and "gdfontg.h"
  2307.                 respectively and (if you are not using a library-based
  2308.                 approach) link with the corresponding .c files to use the
  2309.                 provided fonts. The null-terminated string of characters
  2310.                 represented as 16-bit unsigned short integers specified
  2311.                 by the fifth argument is drawn from bottom to top in the
  2312.                 specified color. (See gdImageStringUp16 for a way of
  2313.                 drawing horizontal text.) Pixels not set by a particular
  2314.                 character retain their previous color.
  2315.                 
  2316.                 This function was added in gd1.3 to provide a means of
  2317.                 rendering fonts with more than 256 characters for those
  2318.                 who have them. A more frequently used routine is
  2319.                 gdImageStringUp.
  2320.                 
  2321.         char *gdImageStringFT(gdImagePtr im, int *brect, int fg, char
  2322.                 *fontname, double ptsize, double angle, int x, int y,
  2323.                 char *string) _(FUNCTION)_
  2324.                 _RECOMMENDED. New in 1.8.4._ gdImageStringFT draws text
  2325.                 using the FreeType 2.x library.
  2326.                 
  2327.                 gdImageStringFT draws a string of anti-aliased characters
  2328.                 on the image using the FreeType library to render
  2329.                 user-supplied TrueType fonts. _We do not provide TrueType
  2330.                 fonts (.ttf and .ttc files). Obtaining them is entirely
  2331.                 up to you._ The string is anti-aliased, meaning that
  2332.                 there should be fewer "jaggies" visible. The fontname is
  2333.                 the full pathname to a TrueType font file, or a font face
  2334.                 name if the GDFONTPATH environment variable or FreeType's
  2335.                 DEFAULT_FONTPATH variable have been set intelligently.
  2336.                 The string may be arbitrarily scaled (ptsize) and rotated
  2337.                 (angle in radians).
  2338.                 
  2339.                 The user-supplied int brect[8] array is filled on return
  2340.                 from gdImageStringFT with the 8 elements representing the
  2341.                 4 corner coordinates of the bounding rectangle.
  2342.                 0 lower left corner, X position
  2343.                 lower left corner, Y position
  2344.                 lower right corner, X position
  2345.                 3 lower right corner, Y position
  2346.                 4 upper right corner, X position
  2347.                 5 upper right corner, Y position
  2348.                 6 upper left corner, X position
  2349.                 7 upper left corner, Y position
  2350.                 
  2351.                 The points are relative to the text regardless of the
  2352.                 angle, so "upper left" means in the top left-hand corner
  2353.                 seeing the text horizontally.
  2354.                 
  2355.                 Use a NULL gdImagePtr to get the bounding rectangle
  2356.                 without rendering. This is a relatively cheap operation
  2357.                 if followed by a rendering of the same string, because of
  2358.                 the caching of the partial rendering during bounding
  2359.                 rectangle calculation.
  2360.                 
  2361.                 The string is rendered in the color indicated by the gf
  2362.                 color index. _Use the negative of the desired color index
  2363.                 to disable anti-aliasing._
  2364.                 
  2365.                 The string may contain UTF-8 sequences like: "À"
  2366.                 
  2367.                 gdImageStringFT will return a null char* on success, or
  2368.                 an error string on failure.
  2369.                 
  2370.  
  2371. #include "gd.h"
  2372. #include <string.h>
  2373. ... inside a function ...
  2374. gdImagePtr im;
  2375. int black;
  2376. int white;
  2377. int brect[8];
  2378. int x, y;
  2379. char *err;
  2380.  
  2381. char *s = "Hello."; /* String to draw. */
  2382. double sz = 40.;
  2383. char *f = "/usr/local/share/ttf/Times.ttf";  /* User supplied font */
  2384.  
  2385. /* obtain brect so that we can size the image */
  2386. err = gdImageStringFT(NULL,&brect[0],0,f,sz,0.,0,0,s);
  2387. if (err) {fprintf(stderr,err); return 1;}
  2388.  
  2389. /* create an image big enough for the string plus a little whitespace */
  2390. x = brect[2]-brect[6] + 6;
  2391. y = brect[3]-brect[7] + 6;
  2392. im = gdImageCreate(x,y);
  2393.  
  2394. /* Background color (first allocated) */
  2395. white = gdImageColorResolve(im, 255, 255, 255);
  2396. black = gdImageColorResolve(im, 0, 0, 0);
  2397.  
  2398. /* render the string, offset origin to center string*/
  2399. /* note that we use top-left coordinate for adjustment
  2400.  * since gd origin is in top-left with y increasing downwards. */
  2401. x = 3 - brect[6];
  2402. y = 3 - brect[7];
  2403. err = gdImageStringFT(im,&brect[0],black,f,sz,0.0,x,y,s);
  2404. if (err) {fprintf(stderr,err); return 1;}
  2405.  
  2406. /* Write img to stdout */
  2407. gdImagePng(im, stdout);
  2408.  
  2409. /* Destroy it */
  2410. gdImageDestroy(im);
  2411.  
  2412.         char *gdImageStringTTF(gdImagePtr im, int *brect, int fg, char
  2413.                 *fontname, double ptsize, double angle, int x, int y,
  2414.                 char *string) _(FUNCTION)_
  2415.                 _DEPRECATED._ THis function simply invokes
  2416.                 gdImageStringFT for backwards compatibility with old code
  2417.                 that was written with FreeType 1.x. /DL>
  2418.                 
  2419.   Color-handling functions
  2420.   
  2421.               int gdImageColorAllocate(gdImagePtr im, int r, int g, int
  2422.                       b) _(FUNCTION)_
  2423.                       gdImageColorAllocate finds the first available
  2424.                       color index in the image specified, sets its RGB
  2425.                       values to those requested (255 is the maximum for
  2426.                       each), and returns the index of the new color table
  2427.                       entry, or an RGBA value in the case of a truecolor
  2428.                       image; in either case you can then use the returned
  2429.                       value as a parameter to drawing functions. When
  2430.                       creating a new palette-based image, the first time
  2431.                       you invoke this function, you are setting the
  2432.                       background color for that image.
  2433.                       
  2434.                       In the event that all gdMaxColors colors (256) have
  2435.                       already been allocated, gdImageColorAllocate will
  2436.                       return -1 to indicate failure. (This is not
  2437.                       uncommon when working with existing PNG files that
  2438.                       already use 256 colors.) Note that
  2439.                       gdImageColorAllocate does not check for existing
  2440.                       colors that match your request; see
  2441.                       gdImageColorExact, gdImageColorClosest and
  2442.                       gdImageColorClosestHWB for ways to locate existing
  2443.                       colors that approximate the color desired in
  2444.                       situations where a new color is not available. Also
  2445.                       see gdImageColorResolve, new in gd-1.6.2.
  2446.                       
  2447.  
  2448. ... inside a function ...
  2449. gdImagePtr im;
  2450. int black;
  2451. int red;
  2452. im = gdImageCreate(100, 100);
  2453. /* Background color (first allocated) */
  2454. black = gdImageColorAllocate(im, 0, 0, 0);
  2455. /* Allocate the color red. */
  2456. red = gdImageColorAllocate(im, 255, 0, 0);
  2457. /* Draw a dashed line from the upper left corner to the lower right corner. */
  2458. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2459. /* ... Do something with the image, such as saving it to a file... */
  2460. /* Destroy it */
  2461. gdImageDestroy(im);
  2462.  
  2463.               int gdImageColorAllocateAlpha(gdImagePtr im, int r, int g,
  2464.                       int b, int a) _(FUNCTION)_
  2465.                       gdImageColorAllocateAlpha finds the first available
  2466.                       color index in the image specified, sets its RGBA
  2467.                       values to those requested (255 is the maximum for
  2468.                       red, green and blue, and 127 represents full
  2469.                       transparency for alpha), and returns the index of
  2470.                       the new color table entry, or an RGBA value in the
  2471.                       case of a truecolor image; in either case you can
  2472.                       then use the returned value as a parameter to
  2473.                       drawing functions. When creating a new
  2474.                       palette-based image, the first time you invoke this
  2475.                       function, you are setting the background color for
  2476.                       that image.
  2477.                       
  2478.                       In the event that all gdMaxColors colors (256) have
  2479.                       already been allocated, gdImageColorAllocate will
  2480.                       return -1 to indicate failure. (This is not
  2481.                       uncommon when working with existing palette-based
  2482.                       PNG files that already use 256 colors.) Note that
  2483.                       gdImageColorAllocateAlpha does not check for
  2484.                       existing colors that match your request; see
  2485.                       gdImageColorExactAlpha and gdImageColorClosestAlpha
  2486.                       for ways to locate existing colors that approximate
  2487.                       the color desired in situations where a new color
  2488.                       is not available. Also see
  2489.                       gdImageColorResolveAlpha.
  2490.                       
  2491.  
  2492. ... inside a function ...
  2493. gdImagePtr im;
  2494. int black;
  2495. int red;
  2496. im = gdImageCreate(100, 100);
  2497. /* Background color (first allocated) */
  2498. black = gdImageColorAllocate(im, 0, 0, 0);
  2499. /* Allocate the color red, 50% transparent. */
  2500. red = gdImageColorAllocateAlpha(im, 255, 0, 0, 64);
  2501. /* Draw a dashed line from the upper left corner to the lower right corner. */
  2502. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2503. /* ... Do something with the image, such as saving it to a file... */
  2504. /* Destroy it */
  2505. gdImageDestroy(im);
  2506.  
  2507.               int gdImageColorClosest(gdImagePtr im, int r, int g, int b)
  2508.                       _(FUNCTION)_
  2509.                       gdImageColorClosest searches the colors which have
  2510.                       been defined thus far in the image specified and
  2511.                       returns the index of the color with RGB values
  2512.                       closest to those of the request. (Closeness is
  2513.                       determined by Euclidian distance, which is used to
  2514.                       determine the distance in three-dimensional color
  2515.                       space between colors.)
  2516.                       
  2517.                       If no colors have yet been allocated in the image,
  2518.                       gdImageColorClosest returns -1.
  2519.                       
  2520.                       When applied to a truecolor image, this function
  2521.                       always succeeds in returning the desired color.
  2522.                       
  2523.                       This function is most useful as a backup method for
  2524.                       choosing a drawing color when an image already
  2525.                       contains gdMaxColors (256) colors and no more can
  2526.                       be allocated. (This is not uncommon when working
  2527.                       with existing PNG files that already use many
  2528.                       colors.) See gdImageColorExact for a method of
  2529.                       locating exact matches only.
  2530.                       
  2531.  
  2532. ... inside a function ...
  2533. gdImagePtr im;
  2534. FILE *in;
  2535. int red;
  2536. /* Let's suppose that photo.png is a scanned photograph with
  2537.         many colors. */
  2538. in = fopen("photo.png", "rb");
  2539. im = gdImageCreateFromPng(in);
  2540. fclose(in);
  2541. /* Try to allocate red directly */
  2542. red = gdImageColorAllocate(im, 255, 0, 0);
  2543. /* If we fail to allocate red... */
  2544. if (red == (-1)) {
  2545.         /* Find the _closest_ color instead. */
  2546.         red = gdImageColorClosest(im, 255, 0, 0);
  2547. }
  2548. /* Draw a dashed line from the upper left corner to the lower right corner */
  2549. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2550. /* ... Do something with the image, such as saving it to a file... */
  2551. /* Destroy it */
  2552. gdImageDestroy(im);
  2553.  
  2554.               int gdImageColorClosestAlpha(gdImagePtr im, int r, int g,
  2555.                       int b, int a) _(FUNCTION)_
  2556.                       gdImageColorClosest searches the colors which have
  2557.                       been defined thus far in the image specified and
  2558.                       returns the index of the color with RGBA values
  2559.                       closest to those of the request. (Closeness is
  2560.                       determined by Euclidian distance, which is used to
  2561.                       determine the distance in four-dimensional
  2562.                       color/alpha space between colors.)
  2563.                       
  2564.                       If no colors have yet been allocated in the image,
  2565.                       gdImageColorClosestAlpha returns -1.
  2566.                       
  2567.                       When applied to a truecolor image, this function
  2568.                       always succeeds in returning the desired color.
  2569.                       
  2570.                       This function is most useful as a backup method for
  2571.                       choosing a drawing color when a palette-based image
  2572.                       already contains gdMaxColors (256) colors and no
  2573.                       more can be allocated. (This is not uncommon when
  2574.                       working with existing palette-based PNG files that
  2575.                       already use many colors.) See
  2576.                       gdImageColorExactAlpha for a method of locating
  2577.                       exact matches only.
  2578.                       
  2579.  
  2580. ... inside a function ...
  2581. gdImagePtr im;
  2582. FILE *in;
  2583. int red;
  2584. /* Let's suppose that photo.png is a scanned photograph with
  2585.         many colors. */
  2586. in = fopen("photo.png", "rb");
  2587. im = gdImageCreateFromPng(in);
  2588. fclose(in);
  2589. /* Try to allocate red, 50% transparent, directly */
  2590. red = gdImageColorAllocateAlpha(im, 255, 0, 0, 64);
  2591. /* If we fail to allocate red... */
  2592. if (red == (-1)) {
  2593.         /* Find the _closest_ color instead. */
  2594.         red = gdImageColorClosestAlpha(im, 255, 0, 0, 64);
  2595. }
  2596. /* Draw a dashed line from the upper left corner to the lower right corner */
  2597. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2598. /* ... Do something with the image, such as saving it to a file... */
  2599. /* Destroy it */
  2600. gdImageDestroy(im);
  2601.  
  2602.               int gdImageColorClosestHWB(gdImagePtr im, int r, int g, int
  2603.                       b) _(FUNCTION)_
  2604.                       gdImageColorClosestHWB searches the colors which
  2605.                       have been defined thus far in the image specified
  2606.                       and returns the index of the color with hue,
  2607.                       whiteness and blackness closest to the requested
  2608.                       color. This scheme is typically superior to the
  2609.                       Euclidian distance scheme used by
  2610.                       gdImageColorClosest.
  2611.                       
  2612.                       If no colors have yet been allocated in the image,
  2613.                       gdImageColorClosestHWB returns -1.
  2614.                       
  2615.                       When applied to a truecolor image, this function
  2616.                       always succeeds in returning the desired color.
  2617.                       
  2618.                       This function is most useful as a backup method for
  2619.                       choosing a drawing color when an image already
  2620.                       contains gdMaxColors (256) colors and no more can
  2621.                       be allocated. (This is not uncommon when working
  2622.                       with existing PNG files that already use many
  2623.                       colors.) See gdImageColorExact for a method of
  2624.                       locating exact matches only.
  2625.                       
  2626.  
  2627. ... inside a function ...
  2628. gdImagePtr im;
  2629. FILE *in;
  2630. int red;
  2631. /* Let's suppose that photo.png is a scanned photograph with
  2632.         many colors. */
  2633. in = fopen("photo.png", "rb");
  2634. im = gdImageCreateFromPng(in);
  2635. fclose(in);
  2636. /* Try to allocate red directly */
  2637. red = gdImageColorAllocate(im, 255, 0, 0);
  2638. /* If we fail to allocate red... */
  2639. if (red == (-1)) {
  2640.         /* Find the _closest_ color instead. */
  2641.         red = gdImageColorClosestHWB(im, 255, 0, 0);
  2642. }
  2643. /* Draw a dashed line from the upper left corner to the lower right corner */
  2644. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2645. /* ... Do something with the image, such as saving it to a file... */
  2646. /* Destroy it */
  2647. gdImageDestroy(im);
  2648.  
  2649.               int gdImageColorExact(gdImagePtr im, int r, int g, int b)
  2650.                       _(FUNCTION)_
  2651.                       gdImageColorExact searches the colors which have
  2652.                       been defined thus far in the image specified and
  2653.                       returns the index of the first color with RGB
  2654.                       values which exactly match those of the request. If
  2655.                       no allocated color matches the request precisely,
  2656.                       gdImageColorExact returns -1. See
  2657.                       gdImageColorClosest for a way to find the color
  2658.                       closest to the color requested.
  2659.                       
  2660.                       When applied to a truecolor image, this function
  2661.                       always succeeds in returning the desired color.
  2662.                       
  2663.  
  2664. ... inside a function ...
  2665. gdImagePtr im;
  2666. int red;
  2667. in = fopen("photo.png", "rb");
  2668. im = gdImageCreateFromPng(in);
  2669. fclose(in);
  2670. /* The image may already contain red; if it does, we'll save a slot
  2671.         in the color table by using that color. */
  2672. /* Try to allocate red directly */
  2673. red = gdImageColorExact(im, 255, 0, 0);
  2674. /* If red isn't already present... */
  2675. if (red == (-1)) {
  2676.         /* Second best: try to allocate it directly. */
  2677.         red = gdImageColorAllocate(im, 255, 0, 0);
  2678.         /* Out of colors, so find the _closest_ color instead. */
  2679.         red = gdImageColorClosest(im, 255, 0, 0);
  2680. }
  2681. /* Draw a dashed line from the upper left corner to the lower right corner */
  2682. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2683. /* ... Do something with the image, such as saving it to a file... */
  2684. /* Destroy it */
  2685. gdImageDestroy(im);
  2686.  
  2687.               int gdImageColorResolve(gdImagePtr im, int r, int g, int b)
  2688.                       _(FUNCTION)_
  2689.                       gdImageColorResolve searches the colors which have
  2690.                       been defined thus far in the image specified and
  2691.                       returns the index of the first color with RGB
  2692.                       values which exactly match those of the request. If
  2693.                       no allocated color matches the request precisely,
  2694.                       then gdImageColorResolve tries to allocate the
  2695.                       exact color. If there is no space left in the color
  2696.                       table then gdImageColorResolve returns the closest
  2697.                       color (as in gdImageColorClosest). This function
  2698.                       always returns an index of a color.
  2699.                       
  2700.                       When applied to a truecolor image, this function
  2701.                       always succeeds in returning the desired color.
  2702.                       
  2703.  
  2704. ... inside a function ...
  2705. gdImagePtr im;
  2706. int red;
  2707. in = fopen("photo.png", "rb");
  2708. im = gdImageCreateFromPng(in);
  2709. fclose(in);
  2710. /* The image may already contain red; if it does, we'll save a slot
  2711.         in the color table by using that color. */
  2712. /* Get index of red, or color closest to red */
  2713. red = gdImageColorResolve(im, 255, 0, 0);
  2714. /* Draw a dashed line from the upper left corner to the lower right corner */
  2715. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2716. /* ... Do something with the image, such as saving it to a file... */
  2717. /* Destroy it */
  2718. gdImageDestroy(im);
  2719.  
  2720.               int gdImageColorResolveAlpha(gdImagePtr im, int r, int g,
  2721.                       int b, int a) _(FUNCTION)_
  2722.                       gdImageColorResolveAlpha searches the colors which
  2723.                       have been defined thus far in the image specified
  2724.                       and returns the index of the first color with RGBA
  2725.                       values which exactly match those of the request. If
  2726.                       no allocated color matches the request precisely,
  2727.                       then gdImageColorResolveAlpha tries to allocate the
  2728.                       exact color. If there is no space left in the color
  2729.                       table then gdImageColorResolveAlpha returns the
  2730.                       closest color (as in gdImageColorClosestAlpha).
  2731.                       This function always returns an index of a color.
  2732.                       
  2733.                       When applied to a truecolor image, this function
  2734.                       always succeeds in returning the desired color.
  2735.                       
  2736.  
  2737. ... inside a function ...
  2738. gdImagePtr im;
  2739. int red;
  2740. in = fopen("photo.png", "rb");
  2741. im = gdImageCreateFromPng(in);
  2742. fclose(in);
  2743. /* The image may already contain red; if it does, we'll save a slot
  2744.         in the color table by using that color. */
  2745. /* Get index of red, 50% transparent, or the next best thing */
  2746. red = gdImageColorResolveAlpha(im, 255, 0, 0, 64);
  2747. /* Draw a dashed line from the upper left corner to the lower right corner */
  2748. gdImageDashedLine(im, 0, 0, 99, 99, red);
  2749. /* ... Do something with the image, such as saving it to a file... */
  2750. /* Destroy it */
  2751. gdImageDestroy(im);
  2752.  
  2753.               int gdImageColorsTotal(gdImagePtr im) _(MACRO)_
  2754.                       gdImageColorsTotal is a macro which returns the
  2755.                       number of colors currently allocated in a palette
  2756.                       image. For truecolor images, the result of this
  2757.                       call is undefined and should not be used.
  2758.                       
  2759.               int gdImageColorRed(gdImagePtr im, int c) _(MACRO)_
  2760.                       gdImageColorRed is a macro which returns the red
  2761.                       portion of the specified color in the image. This
  2762.                       macro works for both palette and truecolor images.
  2763.                       
  2764.               int gdImageColorGreen(gdImagePtr im, int c) _(MACRO)_
  2765.                       gdImageColorGreen is a macro which returns the
  2766.                       green portion of the specified color in the image.
  2767.                       This macro works for both palette and truecolor
  2768.                       images.
  2769.                       
  2770.               int gdImageColorBlue(gdImagePtr im, int c) _(MACRO)_
  2771.                       gdImageColorBlue is a macro which returns the green
  2772.                       portion of the specified color in the image. This
  2773.                       macro works for both palette and truecolor images.
  2774.                       
  2775.               int gdImageGetInterlaced(gdImagePtr im) _(MACRO)_
  2776.                       gdImageGetInterlaced is a macro which returns true
  2777.                       (1) if the image is interlaced, false (0) if not.
  2778.                       Use this macro to obtain this information; do not
  2779.                       access the structure directly. See gdImageInterlace
  2780.                       for a means of interlacing images.
  2781.                       
  2782.               int gdImageGetTransparent(gdImagePtr im) _(MACRO)_
  2783.                       gdImageGetTransparent is a macro which returns the
  2784.                       current transparent color index in the image. If
  2785.                       there is no transparent color,
  2786.                       gdImageGetTransparent returns -1. Use this macro to
  2787.                       obtain this information; do not access the
  2788.                       structure directly.
  2789.                       
  2790.               void gdImageColorDeallocate(gdImagePtr im, int color)
  2791.                       _(FUNCTION)_
  2792.                       gdImageColorDeallocate marks the specified color as
  2793.                       being available for reuse. It does not attempt to
  2794.                       determine whether the color index is still in use
  2795.                       in the image. After a call to this function, the
  2796.                       next call to gdImageColorAllocate for the same
  2797.                       image will set new RGB values for that color index,
  2798.                       changing the color of any pixels which have that
  2799.                       index as a result. If multiple calls to
  2800.                       gdImageColorDeallocate are made consecutively, the
  2801.                       lowest-numbered index among them will be reused by
  2802.                       the next gdImageColorAllocate call.
  2803.                       
  2804.  
  2805. ... inside a function ...
  2806. gdImagePtr im;
  2807. int red, blue;
  2808. in = fopen("photo.png", "rb");
  2809. im = gdImageCreateFromPng(in);
  2810. fclose(in);
  2811. /* Look for red in the color table. */
  2812. red = gdImageColorExact(im, 255, 0, 0);
  2813. /* If red is present... */
  2814. if (red != (-1)) {
  2815.         /* Deallocate it. */
  2816.         gdImageColorDeallocate(im, red);
  2817.         /* Allocate blue, reusing slot in table.
  2818.                 Existing red pixels will change color. */
  2819.         blue = gdImageColorAllocate(im, 0, 0, 255);
  2820. }
  2821. /* ... Do something with the image, such as saving it to a file... */
  2822. /* Destroy it */
  2823. gdImageDestroy(im);
  2824.  
  2825.               void gdImageColorTransparent(gdImagePtr im, int color)
  2826.                       _(FUNCTION)_
  2827.                       gdImageColorTransparent sets the transparent color
  2828.                       index for the specified image to the specified
  2829.                       index. To indicate that there should be _no_
  2830.                       transparent color, invoke gdImageColorTransparent
  2831.                       with a color index of -1. Note that JPEG images do
  2832.                       not support transparency, so this setting has no
  2833.                       effect when writing JPEG images.
  2834.                       
  2835.                       The color index used should be an index allocated
  2836.                       by gdImageColorAllocate, whether explicitly invoked
  2837.                       by your code or implicitly invoked by loading an
  2838.                       image. In order to ensure that your image has a
  2839.                       reasonable appearance when viewed by users who do
  2840.                       not have transparent background capabilities (or
  2841.                       when you are writing a JPEG-format file, which does
  2842.                       not support transparency), be sure to give
  2843.                       reasonable RGB values to the color you allocate for
  2844.                       use as a transparent color, _even though it will be
  2845.                       transparent on systems that support PNG
  2846.                       transparency_.
  2847.                       
  2848.  
  2849. ... inside a function ...
  2850. gdImagePtr im;
  2851. int black;
  2852. FILE *in, *out;
  2853. in = fopen("photo.png", "rb");
  2854. im = gdImageCreateFromPng(in);
  2855. fclose(in);
  2856. /* Look for black in the color table and make it transparent. */
  2857. black = gdImageColorExact(im, 0, 0, 0);
  2858. /* If black is present... */
  2859. if (black != (-1)) {
  2860.         /* Make it transparent */
  2861.         gdImageColorTransparent(im, black);
  2862. }
  2863. /* Save the newly-transparent image back to the file */
  2864. out = fopen("photo.png", "wb");
  2865. gdImagePng(im, out);
  2866. fclose(out);
  2867. /* Destroy it */
  2868. gdImageDestroy(im);
  2869.  
  2870.               void gdImageTrueColor(int red, int green, int blue)
  2871.                       _(MACRO)_
  2872.                       gdImageTrueColor returns an RGBA color value for
  2873.                       use when drawing on a truecolor image. Red, green,
  2874.                       and blue are all in the range between 0 (off) and
  2875.                       255 (maximum). This macro should not be used with
  2876.                       palette-based images. If you need to write code
  2877.                       which is compatible with both palette-based and
  2878.                       truecolor images, use gdImageColorResolve.
  2879.                       
  2880.               void gdImageTrueColorAlpha(int red, int green, int blue,
  2881.                       int alpha) _(MACRO)_
  2882.                       gdImageTrueColorAlpha returns an RGBA color value
  2883.                       for use when drawing on a truecolor image with
  2884.                       alpha channel transparency. Red, green, and blue
  2885.                       are all in the range between 0 (off) and 255
  2886.                       (maximum). Alpha is in the range between 0 (opaque)
  2887.                       and 127 (fully transparent). This macro should not
  2888.                       be used with palette-based images. If you need to
  2889.                       write code which is compatible with both
  2890.                       palette-based and truecolor images, use
  2891.                       gdImageColorResolveAlpha.
  2892.                       
  2893.   Copying and resizing functions
  2894.   
  2895.               void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX,
  2896.                       int dstY, int srcX, int srcY, int w, int h)
  2897.                       _(FUNCTION)_
  2898.                       gdImageCopy is used to copy a rectangular portion
  2899.                       of one image to another image. (For a way of
  2900.                       stretching or shrinking the image in the process,
  2901.                       see gdImageCopyResized.)
  2902.                       
  2903.                       The dst argument is the destination image to which
  2904.                       the region will be copied. The src argument is the
  2905.                       source image from which the region is copied. The
  2906.                       dstX and dstY arguments specify the point in the
  2907.                       destination image to which the region will be
  2908.                       copied. The srcX and srcY arguments specify the
  2909.                       upper left corner of the region in the source
  2910.                       image. The w and h arguments specify the width and
  2911.                       height of the region.
  2912.                       
  2913.                       When you copy a region from one location in an
  2914.                       image to another location in the same image,
  2915.                       gdImageCopy will perform as expected unless the
  2916.                       regions overlap, in which case the result is
  2917.                       unpredictable.
  2918.                       
  2919.                       _Important note on copying between images:_ since
  2920.                       different images do not necessarily have the same
  2921.                       color tables, pixels are not simply set to the same
  2922.                       color index values to copy them. gdImageCopy will
  2923.                       attempt to find an identical RGB value in the
  2924.                       destination image for each pixel in the copied
  2925.                       portion of the source image by invoking
  2926.                       gdImageColorExact. If such a value is not found,
  2927.                       gdImageCopy will attempt to allocate colors as
  2928.                       needed using gdImageColorAllocate. If both of these
  2929.                       methods fail, gdImageCopy will invoke
  2930.                       gdImageColorClosest to find the color in the
  2931.                       destination image which most closely approximates
  2932.                       the color of the pixel being copied.
  2933.                       
  2934.  
  2935. ... Inside a function ...
  2936. gdImagePtr im_in;
  2937. gdImagePtr im_out;
  2938. int x, y;
  2939. FILE *in;
  2940. FILE *out;
  2941. /* Load a small png to tile the larger one with */
  2942. in = fopen("small.png", "rb");
  2943. im_in = gdImageCreateFromPng(in);
  2944. fclose(in);
  2945. /* Make the output image four times as large on both axes */
  2946. im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
  2947. /* Now tile the larger image using the smaller one */
  2948. for (y = 0; (y < 4); y++) {
  2949.         for (x = 0; (x < 4); x++) {
  2950.                 gdImageCopy(im_out, im_in,
  2951.                         x * im_in->sx, y * im_in->sy,
  2952.                         0, 0,
  2953.                         im_in->sx, im_in->sy);
  2954.         }
  2955. }
  2956. out = fopen("tiled.png", "wb");
  2957. gdImagePng(im_out, out);
  2958. fclose(out);
  2959. gdImageDestroy(im_in);
  2960. gdImageDestroy(im_out);
  2961.  
  2962.               void gdImageCopyResized(gdImagePtr dst, gdImagePtr src, int
  2963.                       dstX, int dstY, int srcX, int srcY, int destW, int
  2964.                       destH, int srcW, int srcH) _(FUNCTION)_
  2965.                       gdImageCopyResized is used to copy a rectangular
  2966.                       portion of one image to another image. The X and Y
  2967.                       dimensions of the original region and the
  2968.                       destination region can vary, resulting in
  2969.                       stretching or shrinking of the region as
  2970.                       appropriate. (For a simpler version of this
  2971.                       function which does not deal with resizing, see
  2972.                       gdImageCopy.)
  2973.                       
  2974.                       The dst argument is the destination image to which
  2975.                       the region will be copied. The src argument is the
  2976.                       source image from which the region is copied. The
  2977.                       dstX and dstY arguments specify the point in the
  2978.                       destination image to which the region will be
  2979.                       copied. The srcX and srcY arguments specify the
  2980.                       upper left corner of the region in the source
  2981.                       image. The dstW and dstH arguments specify the
  2982.                       width and height of the destination region. The
  2983.                       srcW and srcH arguments specify the width and
  2984.                       height of the source region and can differ from the
  2985.                       destination size, allowing a region to be scaled
  2986.                       during the copying process.
  2987.                       
  2988.                       When you copy a region from one location in an
  2989.                       image to another location in the same image,
  2990.                       gdImageCopy will perform as expected unless the
  2991.                       regions overlap, in which case the result is
  2992.                       unpredictable. If this presents a problem, create a
  2993.                       scratch image in which to keep intermediate
  2994.                       results.
  2995.                       
  2996.                       _Important note on copying between images:_ since
  2997.                       images do not necessarily have the same color
  2998.                       tables, pixels are not simply set to the same color
  2999.                       index values to copy them. gdImageCopy will attempt
  3000.                       to find an identical RGB value in the destination
  3001.                       image for each pixel in the copied portion of the
  3002.                       source image by invoking gdImageColorExact. If such
  3003.                       a value is not found, gdImageCopy will attempt to
  3004.                       allocate colors as needed using
  3005.                       gdImageColorAllocate. If both of these methods
  3006.                       fail, gdImageCopy will invoke gdImageColorClosest
  3007.                       to find the color in the destination image which
  3008.                       most closely approximates the color of the pixel
  3009.                       being copied.
  3010.                       
  3011.  
  3012. ... Inside a function ...
  3013. gdImagePtr im_in;
  3014. gdImagePtr im_out;
  3015. int x, y;
  3016. FILE *in;
  3017. FILE *out;
  3018. /* Load a small png to expand in the larger one */
  3019. in = fopen("small.png", "rb");
  3020. im_in = gdImageCreateFromPng(in);
  3021. fclose(in);
  3022. /* Make the output image four times as large on both axes */
  3023. im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
  3024. /* Now copy the smaller image, but four times larger */
  3025. gdImageCopyResized(im_out, im_in, 0, 0, 0, 0,
  3026.         im_out->sx, im_out->sy,
  3027.         im_in->sx, im_in->sy);
  3028. out = fopen("large.png", "wb");
  3029. gdImagePng(im_out, out);
  3030. fclose(out);
  3031. gdImageDestroy(im_in);
  3032. gdImageDestroy(im_out);
  3033.  
  3034.               void gdImageCopyResampled(gdImagePtr dst, gdImagePtr src,
  3035.                       int dstX, int dstY, int srcX, int srcY, int destW,
  3036.                       int destH, int srcW, int srcH) _(FUNCTION)_
  3037.                       gdImageCopyResampled is used to copy a rectangular
  3038.                       portion of one image to another image, smoothly
  3039.                       interpolating pixel values so that, in particular,
  3040.                       reducing the size of an image still retains a great
  3041.                       deal of clarity. The X and Y dimensions of the
  3042.                       original region and the destination region can
  3043.                       vary, resulting in stretching or shrinking of the
  3044.                       region as appropriate. (For a simpler version of
  3045.                       this function which does not deal with resizing,
  3046.                       see gdImageCopy. For a version which does not
  3047.                       interpolate pixel values, see gdImageCopyResized.
  3048.                       
  3049.                       Pixel values are only interpolated if the
  3050.                       destination image is a truecolor image. Otherwise,
  3051.                       gdImageCopyResized is automatically invoked.
  3052.                       
  3053.                       The dst argument is the destination image to which
  3054.                       the region will be copied. The src argument is the
  3055.                       source image from which the region is copied. The
  3056.                       dstX and dstY arguments specify the point in the
  3057.                       destination image to which the region will be
  3058.                       copied. The srcX and srcY arguments specify the
  3059.                       upper left corner of the region in the source
  3060.                       image. The dstW and dstH arguments specify the
  3061.                       width and height of the destination region. The
  3062.                       srcW and srcH arguments specify the width and
  3063.                       height of the source region and can differ from the
  3064.                       destination size, allowing a region to be scaled
  3065.                       during the copying process.
  3066.                       
  3067.                       When you copy a region from one location in an
  3068.                       image to another location in the same image,
  3069.                       gdImageCopy will perform as expected unless the
  3070.                       regions overlap, in which case the result is
  3071.                       unpredictable. If this presents a problem, create a
  3072.                       scratch image in which to keep intermediate
  3073.                       results.
  3074.                       
  3075.                       _Important note on copying between images:_ since
  3076.                       images do not necessarily have the same color
  3077.                       tables, pixels are not simply set to the same color
  3078.                       index values to copy them. If the destination image
  3079.                       is a palette image, gd will use the
  3080.                       gdImageColorResolve function to determine the best
  3081.                       color available.
  3082.                       
  3083.  
  3084. ... Inside a function ...
  3085. gdImagePtr im_in;
  3086. gdImagePtr im_out;
  3087. int x, y;
  3088. FILE *in;
  3089. FILE *out;
  3090. /* Load a large png to shrink in the smaller one */
  3091. in = fopen("large.png", "rb");
  3092. im_in = gdImageCreateFromPng(in);
  3093. fclose(in);
  3094. /* Make the output image four times as small on both axes. Use
  3095.         a true color image so that we can interpolate colors. */
  3096. im_out = gdImageCreateTrueColor(im_in->sx / 4, im_in->sy / 4);
  3097. /* Now copy the large image, but four times smaller */
  3098. gdImageCopyResampled(im_out, im_in, 0, 0, 0, 0,
  3099.         im_out->sx, im_out->sy,
  3100.         im_in->sx, im_in->sy);
  3101. out = fopen("large.png", "wb");
  3102. gdImagePng(im_out, out);
  3103. fclose(out);
  3104. gdImageDestroy(im_in);
  3105. gdImageDestroy(im_out);
  3106.  
  3107.               void gdImageCopyMerge(gdImagePtr dst, gdImagePtr src, int
  3108.                       dstX, int dstY, int srcX, int srcY, int w, int h,
  3109.                       int pct) _(FUNCTION)_
  3110.                       gdImageCopyMerge is almost identical to
  3111.                       gdImageCopy, except that it 'merges' the two images
  3112.                       by an amount specified in the last parameter. If
  3113.                       the last parameter is 100, then it will function
  3114.                       identically to gdImageCopy - the source image
  3115.                       replaces the pixels in the destination.
  3116.                       
  3117.                       If, however, the _pct_ parameter is less than 100,
  3118.                       then the two images are merged. With pct = 0, no
  3119.                       action is taken.
  3120.                       
  3121.                       This feature is most useful to 'highlight' sections
  3122.                       of an image by merging a solid color with pct = 50:
  3123.                       
  3124.  
  3125. ... Inside a function ...
  3126. gdImageCopyMerge(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
  3127.  
  3128.               void gdImageCopyMergeGray(gdImagePtr dst, gdImagePtr src,
  3129.                       int dstX, int dstY, int srcX, int srcY, int w, int
  3130.                       h, int pct) _(FUNCTION)_
  3131.                       gdImageCopyMergeGray is almost identical to
  3132.                       gdImageCopyMerge, except that when merging images
  3133.                       it preserves the hue of the source by converting
  3134.                       the destination pixels to grey scale before the
  3135.                       copy operation.
  3136.                       
  3137.  
  3138. ... Inside a function ...
  3139. gdImageCopyMergeGray(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
  3140.  
  3141.               void gdImagePaletteCopy(gdImagePtr dst, gdImagePtr src)
  3142.                       _(FUNCTION)_
  3143.                       Copies a palette from one image to another,
  3144.                       attempting to match the colors in the target image
  3145.                       to the colors in the source palette.
  3146.                       
  3147.   Miscellaneous Functions
  3148.   
  3149.                     int gdImageCompare(gdImagePtr im1, gdImagePtr im2)
  3150.                             _(FUNCTION)_
  3151.                             gdImageCompare returns a bitmap indicating if
  3152.                             the two images are different. The members of
  3153.                             the bitmap are defined in gd.h, but the most
  3154.                             important is GD_CMP_IMAGE, which indicated
  3155.                             that the images will actually appear
  3156.                             different when displayed. Other, less
  3157.                             important, differences relate to pallette
  3158.                             entries. Any difference in the transparent
  3159.                             colour is assumed to make images display
  3160.                             differently, even if the transparent colour
  3161.                             is not used.
  3162.                             
  3163.  
  3164. ... Inside a function ...
  3165. cmpMask = gdImageCompare(im1, im2);
  3166.  
  3167.                     gdImageInterlace(gdImagePtr im, int interlace)
  3168.                             _(FUNCTION)_
  3169.                             gdImageInterlace is used to determine whether
  3170.                             an image should be stored in a linear
  3171.                             fashion, in which lines will appear on the
  3172.                             display from first to last, or in an
  3173.                             interlaced fashion, in which the image will
  3174.                             "fade in" over several passes. By default,
  3175.                             images are not interlaced. (When writing JPEG
  3176.                             images, interlacing implies generating
  3177.                             progressive JPEG files, which are represented
  3178.                             as a series of scans of increasing quality.
  3179.                             Noninterlaced gd images result in regular
  3180.                             [sequential] JPEG data streams.)
  3181.                             
  3182.                             A nonzero value for the interlace argument
  3183.                             turns on interlace; a zero value turns it
  3184.                             off. Note that interlace has no effect on
  3185.                             other functions, and has no meaning unless
  3186.                             you save the image in PNG or JPEG format; the
  3187.                             gd and xbm formats do not support interlace.
  3188.                             
  3189.                             When a PNG is loaded with
  3190.                             gdImageCreateFromPng or a JPEG is loaded with
  3191.                             gdImageCreateFromJpeg, interlace will be set
  3192.                             according to the setting in the PNG or JPEG
  3193.                             file.
  3194.                             
  3195.                             Note that many PNG and JPEG viewers and web
  3196.                             browsers do _not_ support interlace or the
  3197.                             incremental display of progressive JPEGs.
  3198.                             However, the interlaced PNG or progressive
  3199.                             JPEG should still display; it will simply
  3200.                             appear all at once, just as other images do.
  3201.                             
  3202.  
  3203. gdImagePtr im;
  3204. FILE *out;
  3205. /* ... Create or load the image... */
  3206.  
  3207. /* Now turn on interlace */
  3208. gdImageInterlace(im, 1);
  3209. /* And open an output file */
  3210. out = fopen("test.png", "wb");
  3211. /* And save the image  -- could also use gdImageJpeg */
  3212. gdImagePng(im, out);
  3213. fclose(out);
  3214. gdImageDestroy(im);
  3215.  
  3216.                     gdFree(void *ptr) _(FUNCTION)_
  3217.                             gdFree provides a reliable way to free memory
  3218.                             allocated by functions such as gdImagePngPtr
  3219.                             which return blocks of memory. Use of this
  3220.                             function guarantees that the version of
  3221.                             free() that is ultimately called will be
  3222.                             intended for use with the version of malloc()
  3223.                             that originally allocated the block.
  3224.                             
  3225.   Constants
  3226.   
  3227.                           gdBrushed _(CONSTANT)_
  3228.                                   Used in place of a color when invoking
  3229.                                   a line-drawing function such as
  3230.                                   gdImageLine or gdImageRectangle. When
  3231.                                   gdBrushed is used as the color, the
  3232.                                   brush image set with gdImageSetBrush is
  3233.                                   drawn in place of each pixel of the
  3234.                                   line (the brush is usually larger than
  3235.                                   one pixel, creating the effect of a
  3236.                                   wide paintbrush). See also
  3237.                                   gdStyledBrushed for a way to draw
  3238.                                   broken lines with a series of distinct
  3239.                                   copies of an image.
  3240.                                   
  3241.                           gdMaxColors_(CONSTANT)_
  3242.                                   The constant 256. This is the maximum
  3243.                                   number of colors in a PNG file
  3244.                                   according to the PNG standard, and is
  3245.                                   also the maximum number of colors in a
  3246.                                   gd image.
  3247.                                   
  3248.                           gdStyled _(CONSTANT)_
  3249.                                   Used in place of a color when invoking
  3250.                                   a line-drawing function such as
  3251.                                   gdImageLine or gdImageRectangle. When
  3252.                                   gdStyled is used as the color, the
  3253.                                   colors of the pixels are drawn
  3254.                                   successively from the style that has
  3255.                                   been set with gdImageSetStyle. If the
  3256.                                   color of a pixel is equal to
  3257.                                   gdTransparent, that pixel is not
  3258.                                   altered. (This mechanism is completely
  3259.                                   unrelated to the "transparent color" of
  3260.                                   the image itself; see
  3261.                                   gdImageColorTransparent
  3262.                                   gdImageColorTransparent for that
  3263.                                   mechanism.) See also gdStyledBrushed.
  3264.                                   
  3265.                           gdStyledBrushed _(CONSTANT)_
  3266.                                   Used in place of a color when invoking
  3267.                                   a line-drawing function such as
  3268.                                   gdImageLine or gdImageRectangle. When
  3269.                                   gdStyledBrushed is used as the color,
  3270.                                   the brush image set with
  3271.                                   gdImageSetBrush is drawn at each pixel
  3272.                                   of the line, providing that the style
  3273.                                   set with gdImageSetStyle contains a
  3274.                                   nonzero value (OR gdTransparent, which
  3275.                                   does not equal zero but is supported
  3276.                                   for consistency) for the current pixel.
  3277.                                   (Pixels are drawn successively from the
  3278.                                   style as the line is drawn, returning
  3279.                                   to the beginning when the available
  3280.                                   pixels in the style are exhausted.)
  3281.                                   Note that this differs from the
  3282.                                   behavior of gdStyled, in which the
  3283.                                   values in the style are used as actual
  3284.                                   pixel colors, except for gdTransparent.
  3285.                                   
  3286.                           gdDashSize _(CONSTANT)_
  3287.                                   The length of a dash in a dashed line.
  3288.                                   Defined to be 4 for backwards
  3289.                                   compatibility with programs that use
  3290.                                   gdImageDashedLine. New programs should
  3291.                                   use gdImageSetStyle and call the
  3292.                                   standard gdImageLine function with the
  3293.                                   special "color" gdStyled or
  3294.                                   gdStyledBrushed.
  3295.                                   
  3296.                           gdTiled _(CONSTANT)_
  3297.                                   Used in place of a normal color in
  3298.                                   gdImageFilledRectangle,
  3299.                                   gdImageFilledPolygon, gdImageFill, and
  3300.                                   gdImageFillToBorder. gdTiled selects a
  3301.                                   pixel from the tile image set with
  3302.                                   gdImageSetTile in such a way as to
  3303.                                   ensure that the filled area will be
  3304.                                   tiled with copies of the tile image.
  3305.                                   See the discussions of gdImageFill and
  3306.                                   gdImageFillToBorder for special
  3307.                                   restrictions regarding those functions.
  3308.                                   
  3309.                           gdTransparent _(CONSTANT)_
  3310.                                   Used in place of a normal color in a
  3311.                                   style to be set with gdImageSetStyle.
  3312.                                   gdTransparent is _not_ the transparent
  3313.                                   color index of the image; for that
  3314.                                   functionality please see
  3315.                                   gdImageColorTransparent.
  3316.                                   
  3317.   About the additional .gd image file format
  3318.   
  3319.                                   In addition to reading and writing the
  3320.                                   PNG and JPEG formats and reading the X
  3321.                                   Bitmap format, gd has the capability to
  3322.                                   read and write its own ".gd" format.
  3323.                                   This format is _not_ intended for
  3324.                                   general purpose use and should never be
  3325.                                   used to distribute images. It is not a
  3326.                                   compressed format. Its purpose is
  3327.                                   solely to allow very fast loading of
  3328.                                   images your program needs often in
  3329.                                   order to build other images for output.
  3330.                                   If you are experiencing performance
  3331.                                   problems when loading large, fixed PNG
  3332.                                   images your program needs to produce
  3333.                                   its output images, you may wish to
  3334.                                   examine the functions
  3335.                                   gdImageCreateFromGd and gdImageGd,
  3336.                                   which read and write .gd format images.
  3337.                                   
  3338.                                   The program "pngtogd.c" is provided as
  3339.                                   a simple way of converting .png files
  3340.                                   to .gd format. I emphasize again that
  3341.                                   you will not need to use this format
  3342.                                   unless you have a need for high-speed
  3343.                                   loading of a few frequently-used images
  3344.                                   in your program.
  3345.                                   
  3346.   About the .gd2 image file format
  3347.   
  3348.                                   In addition to reading and writing the
  3349.                                   PNG format and reading the X Bitmap
  3350.                                   format, gd has the capability to read
  3351.                                   and write its own ".gd2" format. This
  3352.                                   format is _not_ intended for general
  3353.                                   purpose use and should never be used to
  3354.                                   distribute images. It is a compressed
  3355.                                   format allowing pseudo-random access to
  3356.                                   large image files. Its purpose is
  3357.                                   solely to allow very fast loading of
  3358.                                   _parts_ of images If you are
  3359.                                   experiencing performance problems when
  3360.                                   loading large, fixed PNG or JPEG images
  3361.                                   your program needs to produce its
  3362.                                   output images, you may wish to examine
  3363.                                   the functions gdImageCreateFromGd2,
  3364.                                   gdImageCreateFromGd2Part and
  3365.                                   gdImageGd2, which read and write .gd2
  3366.                                   format images.
  3367.                                   
  3368.                                   The program "pngtogd2.c" is provided as
  3369.                                   a simple way of converting .png files
  3370.                                   to .gd2 format.
  3371.                                   
  3372.   About the gdIOCtx structure
  3373.   
  3374.                                   Version 1.5 of GD added a new style of
  3375.                                   I/O based on an IOCtx structure (the
  3376.                                   most up-to-date version can be found in
  3377.                                   gd_io.h):
  3378.                                   
  3379.  
  3380. typedef struct gdIOCtx {
  3381.         int     (*getC)(struct gdIOCtx*);
  3382.         int     (*getBuf)(struct gdIOCtx*, void*, int);
  3383.  
  3384.         void     (*putC)(struct gdIOCtx*, int);
  3385.         int     (*putBuf)(struct gdIOCtx*, const void*, int);
  3386.  
  3387.         int     (*seek)(struct gdIOCtx*, const int);
  3388.         long    (*tell)(struct gdIOCtx*);
  3389.  
  3390.         void    (*free)(struct gdIOCtx*);
  3391.  
  3392. } gdIOCtx;
  3393.  
  3394.                           Most functions that accepted files in previous
  3395.                                   versions now also have a counterpart
  3396.                                   that accepts an I/O context. These
  3397.                                   functions have a 'Ctx' suffix.
  3398.                                   
  3399.                                   The Ctx routines use the function
  3400.                                   pointers in the I/O context pointed to
  3401.                                   by gdIOCtx to perform all I/O. Examples
  3402.                                   of how to implement an I/O context can
  3403.                                   be found in io_file.c (which provides a
  3404.                                   wrapper for file routines), and io_dp.c
  3405.                                   (which implements in-memory storage).
  3406.                                   
  3407.                                   It is not necessary to implement all
  3408.                                   functions in an I/O context if you know
  3409.                                   that it will only be used in limited
  3410.                                   cirsumstances. At the time of writing
  3411.                                   (Version 1.6.1, July 1999), the known
  3412.                                   requirements are:
  3413.                                   
  3414.                                   All   Must have 'free',
  3415.                                   Anything that reads from the context
  3416.                                   Must have 'getC' and 'getBuf',
  3417.                                   Anything that writes to the context
  3418.                                   Must have 'putC' and 'putBuf'.
  3419.                                   If gdCreateFromGd2Part is called Must
  3420.                                   also have 'seek' and 'tell'.
  3421.                                   If gdImageGd2 is called Must also have
  3422.                                   'seek' and 'tell'.
  3423.                                   
  3424.   Please tell us you're using gd!
  3425.   
  3426.                                   When you contact us and let us know you
  3427.                                   are using gd, you help us justify the
  3428.                                   time spent in maintaining and improving
  3429.                                   it. So please let us know. If the
  3430.                                   results are publicly visible on the
  3431.                                   web, a URL is a wonderful thing to
  3432.                                   receive, but if it's not a publicly
  3433.                                   visible project, a simple note is just
  3434.                                   as welcome.
  3435.                                   
  3436.   If you have problems
  3437.   
  3438.                                   If you have any difficulties with gd,
  3439.                                   feel free to contact the author, Thomas
  3440.                                   Boutell. Problems relating to the gd2
  3441.                                   format should be addressed to Philip
  3442.                                   Warner.
  3443.                                   
  3444.                                   _Be sure to read this manual carefully
  3445.                                   first. _
  3446.                                   
  3447.   Alphabetical quick index
  3448.   
  3449.                                   gdBrushed | gdDashSize | gdFont |
  3450.                                   gdFontPtr | gdFree | gdImage |
  3451.                                   gdImageAlphaBlending | gdImageArc |
  3452.                                   gdImageBlue | gdImageBoundsSafe |
  3453.                                   gdImageChar | gdImageCharUp |
  3454.                                   gdImageColorAllocate |
  3455.                                   gdImageColorAllocateAlpha |
  3456.                                   gdImageColorClosest |
  3457.                                   gdImageColorClosestAlpha |
  3458.                                   gdImageColorDeallocate |
  3459.                                   gdImageColorExact |
  3460.                                   gdImageColorExactAlpha |
  3461.                                   gdImageColorResolve |
  3462.                                   gdImageColorResolveAlpha |
  3463.                                   gdImageColorTransparent | gdImageCopy |
  3464.                                   gdImageCopyMerge | gdImageMergeGray |
  3465.                                   gdImageCopyResized |
  3466.                                   gdImageCopyResampled | gdImageCreate |
  3467.                                   gdImageCreatePalette |
  3468.                                   gdImageCreateTrueColor |
  3469.                                   gdImageCreateFromGd |
  3470.                                   gdImageCreateFromGd2 |
  3471.                                   gdImageCreateFromGd2Part |
  3472.                                   gdImageCreateFromJpeg |
  3473.                                   gdImageCreateFromPng |
  3474.                                   gdImageCreateFromPngSource |
  3475.                                   gdImageCreateFromXbm |
  3476.                                   gdImageCreateFromXpm |
  3477.                                   gdImageDashedLine | gdImageDestroy |
  3478.                                   gdImageFill | gdImageFilledArc |
  3479.                                   gdImageFilledEllipse |
  3480.                                   gdImageFillToBorder |
  3481.                                   gdImageFilledRectangle | gdImageGd |
  3482.                                   gdImageGd2 | gdImageGetInterlaced |
  3483.                                   gdImageGetPixel | gdImageGetTransparent
  3484.                                   | gdImageGreen | gdImageInterlace |
  3485.                                   gdImageJpeg | gdImageLine |
  3486.                                   gdImageFilledPolygon |
  3487.                                   gdImagePaletteCopy | gdImagePng |
  3488.                                   gdImagePngToSink | gdImagePolygon |
  3489.                                   gdImagePtr | gdImageWBMP |
  3490.                                   gdImageRectangle | gdImageRed |
  3491.                                   gdImageSetBrush | gdImageSetPixel |
  3492.                                   gdImageSetStyle | gdImageSetTile |
  3493.                                   gdImageString | gdImageString16 |
  3494.                                   gdImageStringFT | gdImageStringTTF |
  3495.                                   gdImageStringUp | gdImageStringUp16 |
  3496.                                   gdImageWBMP | gdMaxColors | gdPoint |
  3497.                                   gdStyled | gdStyledBrushed | gdTiled |
  3498.                                   gdTransparent
  3499.                                   
  3500.                                   _Boutell.Com, Inc._
  3501.