= GD extension for TCL. The focus is on output only. For now the model is based on the function calls in GD. Only a modicum of effort is put into encapsulating the commands in an object mechanism. GIF files are disabled in this version, though they may be enabled in the future if solution can be found to the licensing problem. PNG is the default format. JPEG is also supported. Build environment: Requires: (Versions used for development in parentheses) PNG (1.0.8), GD (2.0.1 + extensions), ZLIB (1.1.3) Optional: (Versions used for development in parentheses) JPEG (6b), freetype (2.0.4) Purpose: Writing JPEG and PNG images from Tcl programs. Does not require Tk. GIF support has been removed Model: Currently follows the model for GDI, an experimental extension for use in driving printers. That model, in turn, is based on the Tk canvas model. As with GDI, more options are documented than supported. I like the idea of keeping these two extensions in sync, since the goals are similar--non-interactive drawing output. New or different: o Has NO RELATION to a different product wrapping GD for tcl called 'gdtcl' o Emits palette-based PNG images. o Reads palette-based PNG images (very limited at this time). o Emits ellipses properly. o Uses ellipse code to generate arcs o Supports thicknesses for geometric shapes o Supports Truetype fonts and rotation of text. o No longer supports GIF images o Does NOT support XPM images at this time. Usage: gd [open|close|config|fill|arc|line|oval|polygon|rectangle|text|fontalias|version] General Remarks: Color is specified in any of several ways: - An integer triplet (list) - An octothorp (#) followed by a 6-digit hex value The integers are interpreted as RGB and a color is allocated in the palette if necessary. Color indices are always reused if possible. If no colors remain to allocate, the closest available color is used. - An equal sign (=) followed by a list of integers The integers are interpreted as GD's "styled line" specification. - An ampersand (&) followed by a single integer The integer is interpreted as an existing color index - An at sign (@) followed by a valid image name The image name is used as a GD "brush" - A percent sign (%) followed by a valid image name The image name is used as a GD "tile" Image names are created and returned solely by the "gd open" command and may be used until the "gd close" command operates on them. Image names are validated whenever used in a gd command. An error results if the image name is not valid. gd open gd open -width w -height h -file f -filetype [png|xbm] -background color Creates a new gd image and returns a token for it. The width and height of the image are established at this time and cannot be changed. The width and height are either explicitly set, or are set to the width and height of the image mentioned in the -file argument. If both width and height and file are specified, the width and height of the image are as specified, and the file is scaled to fit into that image. If the file name ends with .png, it is assumed to be a PNG image. If the file name ends with .xbm, it is assumed to be an XBM image. Use of the -filetype argument explicitly documents which kind of image is present. The -background is used to set the background color only on images that were not initialized from files. LIMITATION: Currently only 8-bit paletted PNG images are supported. No checks are currently made on the image type read, so reading a truecolor image will likely cause a core dump. This will be fixed as I understand PNG better and as the "real" design of GD2.0 takes shape. This version uses the GD1.2 code for GIFs instead of the GD1.3 code for GIFs. gd close gd close image [-save [-file filename [-filetype [gif|png] ] ] ] Closing an image will make it invalid for future use. Possibly a 'gd save' command may be implemented to allow intermediate results to be written to a file. If -save is not specified, the image is discarded entirely. If -file is present, -save is assumed; if -file is not present, the filename is 'image.png', and is in PNG format. If -filetype is present, that filetype is explicitly used, irrespective of file name. gd config gd config image [-brush image] [-tile image] [-style int_list] [-interlace 0|1] [-transparent color] [-colormap] [-size] [-fonttable arrayname] The config command is used to access and set many 'image state variables' With no arguments, it provides information about all items that represent the configuration. With an argument and no value, that setting is reported in the return value. With an argument and a value, that setting is changed for the image. gd fill gd fill image x y [-outline color] -fill color Fills the given image starting at the given point with the given fill color. The extension fills in both ways permitted by GD: o If -outline is specified, fills until that color is reached (watch for leaks!) o If -outline is not specified, fills anything matching the color at (x, y), starting at (x, y). LIMITATION: Currently the fill algorithm misbehaves badly when a brush or tile is used as the fill color. Therefore, brushes and tiles are not permitted as fill colors this time. gd arc gd arc image x1 y1 x2 y2 -extent degrees -fill color -outline color -outlinestipple bitmap -start degrees -stipple bitmap -style [pieslice|chord|arc] -width linewid Draws an arc in the image along the orthorectified ellipse circumscribed by (x1,y1) and (x2,y2). Starts at the angle in -start, and extends for the amount specified in -extent. Drawn with the -outline color (or styled line), drawn in the indicated style (arc is the default), and filled with the indicated color (if any). If filled, an 'arc' style is replaced with 'chord'. LIMITATION: -outlinestipple is not supported at this time. Also, the mechanism for drawing wide arcs may need tweaking. gd line gd line image x1 y1 ... xn yn -arrow [first|last|both|none] -arrowshape {d1 d2 d3} -capstyle [butt|projecting|round] -fill color -joinstyle [bevel|miter|round] -smooth [true|false] -splinesteps number -stipple bitmap -width linewid Draws an open polygonal line connecting the points in the indicated order. Uses the specified color (or styled line or brush) to draw the line. LIMITATION: -capstyle, -joinstyle, -smooth, -splinesteps, and -stipple are not supported at this time. [however, using various brushes and styles for the outline can emulate several of these effects] gd oval gd oval image x1 y1 x2 y2 -fill color -outline color -stipple bitmap -width linewid Draws an orthorectified ellipse circumscribed by (x1,y1) and (x2, y2). Uses the indicated outline and fill colors. LIMITATION: -stipple is not supported at this time. Since GD does not support filled ellipses at this time, filling is emulated with the FillToOutline function, with the limitations noted above. In particular, the fill will not work properly if there are embedded shapes in the oval with the same outline color as the oval. Creating a reasonable filled oval is not difficult given the Bresenham algorithm, so this should be fixed soon. gd polygon gd polygon image x1 y1 ... xn yn -fill color -outline color -smooth [true|false] -splinesteps number -stipple bitmap -width linewid Creates a closed polygon with the given vertices, outline, and fill. LIMITATION: -smooth, -splitsteps, and -stipple are not supported at this time. gd rectangle gd rectangle image x1 y1 x2 y2 -fill color -outline color -stipple bitmap -width linewid Creates a rectangle with corners at the given points with the given outline and fill. LIMITATION: -stipple is not supported at this time. gd text gd text image x y -anchor [center|n|e|s|w] -fill color -font fontname -justify [left|right|center] -stipple bitmap -text string -width linelen -anchor [nw|n|ne|w|center|e|sw|s|se] -orientation horizontal|vertical Creates a single line of text with the upper left corner of the first letter at the indiated point with the indicated fill color. Orients text vertically or horizontally as requested. Uses any of the 5 GD fonts: tiny, small, mediumbold, large, and giant. Default is mediumbold. LIMITATION: -stipple is not supported at this time. gd fontalias gd fontalias globspec ... Searches the files matching the specifications to extract font names from those files This, in turn, supports building an aliasing mechanism to suggest which files be used for which fonts. Sample usage set Freetype_Font_Aliases [ gd fontalias [ glob $env(GDFONTPATH)/*.ttf ] ] ... gd configure $im -fonttable Freetype_Font_Aliases (env is a global variable, and im represents an image tag) gd version Prints the current version number of this gd extension (0.3.0.3) Copyright/license notices: ** LIBPNG-1.0.3 ** Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc. Copyright (c) 1996, 1997 Andreas Dilger Copyright (c) 1998, 1999 Glenn Randers-Pehrson The PNG Reference Library (libpng) is supplied "AS IS". The Contributing Authors and Group 42, Inc. disclaim all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The Contributing Authors and Group 42, Inc. assume no liability for direct, indirect, incidental, special, exemplary, or consequential damages, which may result from the use of the PNG Reference Library, even if advised of the possibility of such damage. Permission is hereby granted to use, copy, modify, and distribute this source code, or portions hereof, for any purpose, without fee, subject to the following restrictions: 1. The origin of this source code must not be misrepresented. 2. Altered versions must be plainly marked as such and must not be misrepresented as being the original source. 3. This Copyright notice may not be removed or altered from any source or altered source distribution. The Contributing Authors and Group 42, Inc. specifically permit, without fee, and encourage the use of this source code as a component to supporting the PNG file format in commercial products. If you use this source code in a product, acknowledgment is not required but would be appreciated. ** ZLIB 1.1.3 ** (C) 1995-1998 Jean-loup Gailly and Mark Adler This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. Jean-loup Gailly Mark Adler jloup@gzip.org madler@alumni.caltech.edu If you use the zlib library in a product, we would appreciate *not* receiving lengthy legal documents to sign. The sources are provided for free but without warranty of any kind. The library has been entirely written by Jean-loup Gailly and Mark Adler; it does not include third-party code. If you redistribute modified sources, we would appreciate that you include in the file ChangeLog history information documenting your changes. ** GD ** Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health. Portions copyright 1996, 1997, 1998, 1999, by Boutell.Com, Inc. Portions relating to GD2 format copyright 1999 Philip Warner. Portions relating to PNG copyright 1999, Greg Roelofs. Portions relating to libttf copyright 1999, John Ellson (ellson@lucent.com). _Permission has been granted to copy and distribute gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation._ This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for the authors of gd, not to interfere with your productive use of gd. If you have questions, ask. "Derived works" includes all programs that utilize the library. Credit must be given in user-accessible documentation. _This software is provided "AS IS."_ The copyright holders disclaim all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this code and accompanying documentation. Although their code does not appear in gd 1.6.3, the authors wish to thank David Koblas, David Rowley, and Hutchison Avenue Software Corporation for their prior contributions. *** GD 1.7.3 Modifications GD 1.7.3 modifications copyright Michael I. Schwartz, 1999. Permission is granted to copy and distribute these modifications without fee, provided this copyright notice is maintained. Software modifications are provided AS IS, with no express or implied warranty of any kind. ** FREETYPE 1.2 Copyright 1996 David Turner - 1998 Robert Wilhelm Werner Lemberg The FreeType project is copyright (C) 1996-1998 by David Turner, Robert Wilhelm, and Werner Lemberg. All rights reserved except as specified below. 1. No Warranty: THE FREETYPE ARCHIVE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL ANY OF THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY DAMAGES CAUSED BY THE USE OR THE INABILITY TO USE, OF THE FREETYPE PROJECT. As you have not signed this license, you are not required to accept it. However, as the FreeType project is copyrighted material, only this license, or another one contracted with the authors, grants you the right to use, distribute, and modify it. Therefore, by using, distributing, or modifying the FreeType project, you indicate that you understand and accept all the terms of this license. 2. Redistribution: Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistribution of source code must retain this license file (LICENSE.TXT) unaltered; any additions, deletions or changes to the original files must be clearly indicated in accompanying documentation. All copyright notices must be preserved in all copies of source files. o Redistribution in binary form must provide a disclaimer that states that the software is based in part of the work of the FreeType team in the distribution documentation. We also encourage you to put an URL to the FreeType web page in your documentation, though this isn't mandatory. These conditions apply to any software derived from or based on the FreeType code, not just the unmodified files. If you use our work, you must acknowledge us. However, no fee need be paid to us. ** GD TCL EXTENSION ** Written by Michael I. Schwartz Copyright 1997, 1999 Schwartz Computer Consulting Services Permission granted to use this code in any fashion without fee, provided that this notice is retained and any alterations are labeled as such. The GD TCL extension is provided AS IS, with no express or implied warranty of any kind. In no event will the author or copyright holders be liable for any damages caused by the use or inability to use the GD TCL extension. Tcl Extension for Windows RCS Version $Revision: 1.8 $ RCS Last Change Date: $Date: 2002/01/06 17:54:43 $ Original Author: Michael I. Schwartz, mschwart@nyx.net Note: This is a work in progress. Please coordinate changes with the original author.