OS/2 Shareware BBS: Graphics

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: Graphics / Graphics.zip / gif_text.zip / gif_text.doc < prev next >

Wrap

Text File | 1999-08-16 | 74KB | 1,617 lines

22 June 1999 Contact: danielh@econ.ag.gov GIF_TEXT: A Graphical Text Generator for the WWW GIF_TEXT, ver 1.3b, is a WWW utility that will convert text strings into .GIF images "on the fly". Using one of the several included "alphabytes" it's easy to make attractive banners, headers, and other messages for your web site. For example, GIF_TEXT can dynamically generate the time and date -- you can use GIF_TEXT as a graphical digital-clock. To use GIF_TEXT you should have access to a web server running under OS/2. GIF_TEXT is optimized to work with the free SRE-http Web Server; but you can use it with any OS/2 web server that understands CGI-BIN. Alternatively, you can run GIF_TEXT from an OS/2 command line. Although the user interface is somewhat primitive (it is not GUI), it is quite adequate for quick creation of simple images. Once installed GIF_TEXT is easy to invoke. For example, you can use the included MKGIFTXT.HTM html document as a front-end (or MKGIFRM.HTM -- a javascript/frames enabled version of MKGIFTXT.HTM). Or, you can include an in-line image html element in your HTML document. For example: <IMG src="/GIF_TEXT?font=enviro&text=HELLO&width=300"> will generate a 300 pixel wide image with the word "HELLO" (not including the quotes) written using the "enviro" alphabyte. For those of you who don't have direct access to a web server (i.e.; depend on an ISP), but are running OS/2, you can use GIF_TEXT in stand-alone mode. The user interface is primitive, and there is no direct graphics display, but it will produce fine output (which you can then view with a graphics viewer). Thus, you could use GIF_TEXT to create your images, and then FTP them to your home page at your ISP. And, of course, GIF_TEXT is free (though you should read the acknowledgments section regarding RXGD101.DLL and the various "alphabytes"). Note: You can get the latest version of GIF_TEXT from http://www.srehttp.org/apps/gif_text/ ------------------------------------------------------ Table of Contents: I. Installaton II. Using GIF_TEXT IIa. Short descripton of Request Options II.b Long description of Request Options IIb.1 Required options IIb.2 Recommended options IIb.3 Useful options IIb.4 Infrequently used options III. Technical notes IIIa. Basic File matching algorithim IIIb. Adding an alphabyte IIIc. Adding a background IIId. Adding a complete font IIIe. Adding a TTF font IIIf. Caching images IIIg. On using GIF_TEXT as a "hit counter" IIIh. Using color slides IIIi. Switching fonts in mid-message IV. Sample of a FONT_INDEX IVa. Multiple variants of a "complete font" IVb. Example of adding a new alphabyte V. Acknowledgments ------------------------------------------------------ I. Installation Installation of GIF_TEXT requires that you copy a few files to a few directories, and make a small modification to one of these files. Alternatively, if you are installing GIF_TEXT as an SRE-http addon, the INSTALL.CMD installation program will take care of these details for you. NOTE TO UPGRADERS FROM EARLIER VERSIONS OF GIF_TEXT: Prior to 1.2e, GIF_TEXT used a version of the RXGDUTIL library that lacked several special functions. If you've already installed an earlier version of GIF_TEXT, you'll might have to reboot your server before copying RXGDUTIL.DLL to the appropriate directory (i.e.; your C:\OS2\DLL directory). Furthermore, GIF_text now can read TTF font files -- you no longer have to create a "complete font image map" from a TTF font file. To use these feature, you must set the TTF_FONT_DIR parameter in GIF_TEXT.CMD (SRE-http users can let INSTALL.CMD do it for you) To install GIF_TEXT: 1) UNZIP GIF_TEXT.ZIP in an empty temporary directory. 2a) If you are installing GIF_TEXT as an SRE-http addon: you can run the INSTALL.CMD program (located in the directory created in step 1 above). 2b.1) Otherwise, you can do it by hand... For SRE-http users Copy GIF_TEXT.CMD and MKGIFTXT.CMD to your "SRE-http addon" directory (i.e.; D:\GOSERVE\ADDON). For other, CGI-BIN capable servers: Copy GIF_TEXT.CMD and MKGIFTXT.CMD to your CGI-BIN scripts directory. 2b.2) Copy RXGDUTIL.DLL and RXTTF.DLL to a directory in the OS/2 LIBPATH (for example, C:\OS2\DLL). Or, if you are running SRE-http, copy it to your "GoServe working directory". UPGRADERS -- you might have to reboot your machine if an older version of RXGDUTIL.DLL has been "locked into memory" by a prior use. 2b.3) Create an ALPHABYT directory (say, as a subdirectory of your GOSERVE directory). Copy ALPHABYT.ZIP to this ALPHABYT directory. Note: ALPHABYT.ZIP is over 1M bytes. Example for SRE-http users: create D:\GOSERVE\ALPHABYT 2b.4) CD to this ALPHABYT directory, and UNZIP ALPHABYT. UNZIP will create several subdirectories under ALPHABYT, containing sample "alphabytes", "complete fonts', backgrounds, buttons, and color slides. 2b.5) With your favorite text editor, edit GIF_TEXT.CMD. You MUST i) set the value of the GIF_DIR_ROOT variable to be the above "ALPHABYT" directory ii) set the value of the TTF_DIR_ROOT to point to a directory containing TTF fonts. iii) You might also want to change some of the other values. Notes: * in addition to being the "root" of the alphabytes, etc.; GIF_TEXT uses this GIF_DIR_ROOT directory for temporary storage. * on most systems, the x:\os2\mdos\winos2\system directory contains several ttf fonts. 2b.6) To setup the (optional) MkGifTxt "web callable front end": a) Copy MkGifTxt.HTM, MkGifTx2.HTM and MkGifTx3.HTM to a web accessible directory (i.e.; the GoServe data directory). Also, copy the "frames enabled version", MKGiFRM.HTM and MkGifTOC.HTM, to this directory. b) Copy SAMPGIF.ZIP to the IMGS\ subdirectory under the root of your web directory (for GoServe/SreHttp users: IMGS\ should be under the GoServe data directory). CD to this IMGS\ subdirectory, and UNZIP SAMPGIF. c) If you are using SRE-http, and you want to run MkGifTxt as an "addon" (rather then as a cgi-bin script) -- you'll need to make a very simple change to MkGifTxt.HTM --- see MkGifTxt.HTM for details. d) There are several parameters in MKGIFTXT.CMD that you should change. For example, to use "style" files, you'll need to set the STYLES_DIR parameter in MkGifTxt.CMD. Also, to use the "list fonts, etc" options, make sure the MKGIFTXT.CMD settings for GIF_DIR_ROOT and TTF_DIR_ROOT match those in GIF_TEXT.CMD. 2b.f)To setup the (optional) MkBUTTON "front end" a) Copy MKButton.HTM to a web accessible directory b) Copy ALLBUT1.GIF to the IMGS\ subdirectory under the root of your web directory. c) If you are using SRE-http, and you want to run MKButton as an "addon" (rather then as a cgi-bin script) -- you'll need to make a very simple change to MKButton.HTM --- see MKButton.HTM for details. That's it. Reminder: if you "installed by hand" DON"T FORGET TO DO STEP 2.b5 ! You can point your browser at MKGIFTXT.HTM or MKGIFRM.HTM (did you do step 2b.6?) and try it out: it's a nice way to quickly create "banners" that you can use as static images. Or, you can include <IMG src="/GIF_TEXT?options..> elements in your HTML documents -- a process described in the next section. As mentioned in the introduction, GIF_TEXT can be used in stand-alone mode. From an OS/2 prompt, i) CD (change directory) to the directory that you installed GIF_TEXT ii) enter GIF_TEXT (at the prompt) A Caution to SRE-http users: On some machines, the RXGD101.DLL library used by GIF_TEXT will occassionally generate a SYS3175 error that can crash GoServe. If this should ocur, you may want to err on the side of caution by running GIF_TEXT as a cgi-bin script (since errors that occur whilst executing a cgi-bin script will NOT crash GoServe). However, do note that when run as cgi-bin script, several options (such as the "send in pieces", and "get remote .GIF files") will not be available. ----------------------------------------------------- II. Using GIF_TEXT GIF_TEXT is often invoked using an IMG element (in an HTML document) that contains special "request line options". Several of these options are required (such as the text string), and several are optional (such as background color). This section describes all the GIF_TEXT "requestable" options. Please be aware that default values of many of these options can be set in GIF_TEXT.CMD, and in "font index file". However, request line options take precedence over these defaults. By way of introduction, the following simple examples may help: * When using SRE-http: <IMG src="/GIF_TEXT?text=Welcome+surfers&font=enviro&width=300&as=MESS.GIF"> <IMG src="/GIF_TEXT?text="The time is:$T"&font=andy01&time_Fmt=N&as=MESS.GIF"> The request line options in the first example: text=Welcome+surfers&font=enviro&width=300&as=MESS.GIF and in the second example: text="The time is:$T"&font=andy01&time_Fmt=N&as=MESS.GIF * When using a CGI-BIN capable server: <IMG src="/CGI-BIN/GIF_TEXT?text=Welcome+surfers&font=enviro&width=300&as=MESS.GIF"> <IMG src="/CGI-BIN/GIF_TEXT?text="The time is:$T"&font=andy01&time_Fmt=N&as=MESS.GIF"> (the only difference is the inclusion of a /CGI-BIN before the /GIF_TEXT?) * HINT: the as=MESS.GIF at the end is strictly optional: it is only included to "force" certain browsers to treat the returned image as a .GIF file. For example: when processing in-line images, IBM's Web Explorer expects a .GIF extension and does not pay attention to the mime-type response header. * When run from an OS/2 command line, you can either run GIF_TEXT without an options, or you can specify a set of options. When run without options, GIF_TEXT will ask a series of questions; such as the which font to use, the background, color slide, and image size. When run with options, GIF_TEXT will not prompt you for input, it will read them from the option list. The option list should be a space delimited list, with the format: var=value var=value For example: D:\GIFTEXT>gif_text message=helo font=revue back=backs/pap_gry2 as=foo.gif Note that you MUST include the as=filename option. ---------------- IIa. Short descripton of GIF_TEXT "request line" Options: Required: TEXT : The message to be converted into a graphic. FONT : The alphabyte font to use. Optional, and recommended: WIDTH: The width, in pixels, of the image HEIGHT: The height, in pixels, of the image Optional: AS: File to save GIF image to (command line mode only), TIME_FMT: The format used to display the time. DATE_FMT: The format used to display the date. BACK : A background image for the text BACK_SCALE: Scale or tile the background image X_F: Size of frame (left and right) Y_F: Size of frame (top and bottom) X_OF: Left/right offset Y_OF: Up/down offset X_SCA: A list of "width scales" Y_SCA: A list of "height scales" Y_VAL: Type of vertical (character box) alignment LINE_J: Type of horizontal (line) justification LINE_SEP: Spacing between lines (in pixels) SLIDE: Name of a color slide .GIF file SLIDE_T: Threshold rules (& parameters) for color slides SLIDE_V: Vertical mapping rule for color slides SLIDE_H: Horizontal mapping rule for color slides SLIDE_C: Specify "center coordinates" when using a color slide FIGDIST_T: Method for computing color slide distances SLIDE_SI: Size of "user specified color slide" (# pixels and # colors) SLIDE_RE: Red color parameters for "created slide" SLIDE_GR: Green color parameters for "created slide" SLIDE_BL: Blue color parameters for "created slide" SLIDE_PR: Probability parameters for "using slide value" Optional, infrequently used: FONT_NAME: The "name" of the alphabyte font FONT_INDEX: The "index file" for the alphabyte font TTF_FONT: The TTF font to use TTF_FONT_SIZE: The size (in points) of the TTF font TRANSPARENT: The index of the transparent color BACKCOLOR: The background RGB colors. TEXTCOLOR: The default-font RGB colors LITERAL: Supress $n code interpretation (rarely used) MANY_C: How to choose from a set of complete fonts (multiple complete) SEND: Select "send pieces as they become available" mode Reminder: As noted above,several of these options will override defaults. There are two kinds of defaults: General: Set by variables contained in the user configurable parameters section of GIF_TEXT.CMD. Alphabyte specific: Set in the alphabyte's FONT_INDEX file. ---------------- II.b Long description of Options: IIb.1 ------------ Required TEXT: The message to be converted into a graphic. Example: TEXT=This+is+a+message TEXT should contain an arbitrarily long message. This message should be properly "URL encoded": spaces should be represented by + characters, and certain special characters (such as &, ?, and ") should be coded using the approprate encoding (i.e.; %26 for &). In addition to the keyboard characters, you can include special codes. The most useful special codes are: $t -- include the current time $d -- include the current date. $$ -- the code for the $ character. $b -- filled box: a "rectangular space" filled with the textcolor $n -- new line. Use $n special codes to create a multiple line image. Note that CRLF's (10 and 13 hex) are stripped from the text -- to signify a new line, you must use $N. $F(fontname) -- switch font to the fontname font. $#nnn; -- an ascii code -- nnn is a number between 000 and 255 $#nnx; -- an ascii code -- nn is a hex number between 00 and ff Example: This is umlaut u: $#252; The $#fcx; is umlaut u. You can try these with the COURIER font (note that the ascii codes "escaped" by these $#nnn; sequences matcn ##nn entries in COURIER.IND). CAUTION: Do NOT forget to end these $#nnn with a semi-colon! You can also define your own "special codes". For example, when using the ENVIRO font, a $10 is interpreted as a left quote, and a $11 as a right quote. For further details see the "technical notes" section below. FONT: The "alphabyte" or "complete" font to use. Example: FONT=revue Note: either FONT,or TTF_FONT (and TTF_FONT_SIZE), should always be specified The FONT argument should point to a subdirectory (of the GIF_DIR_ROOT directory) This subdirectory should contain the various .GIF and .IND files that comprise an alphabyte, or a single .GIF file that contains a "complete font". Since most alphabytes do NOT contain .GIF files for all keyboard characters, GIF_TEXT will perform appropriate substitutions. In particular: a) upper case characters will be used if there is no lower case character available b) A "complete font" can be used (if one is specified in the appropriate FONT_INDEX). c) as a last resort, a default (and rather rudimentary) font will be used GIF_TEXT comes packaged with a number of alphabytes, including: Enviro: a subtly colored set of letters (upper and lower case), numbers, and some punctation Revue: a brightly colored set of letters, numbers, and some punctuation Stich: a brightly colored set of letters, numbers, and some punctuation Hobo: a blocky-colorful set of letters and numbers) Mandarin: a multicolored set of letters, numbers, and some punctuation Logger: a woody set of letters andy01 a drippy set of letters and numbers, and some punctuation andy02: a set of typewritter keys (letters only) andy03: an austere set of letters TTF_FONT: A TTF (true type) FONT to use TTF_FONT_SIZE: it's size (in points) Example: TTF_FONT='couri' TTF_FONT_SIZE=30 Note: either FONT, or TTF_FONT (and TTF_FONT_SIZE), should always be specified The TTF_FONT should point to a TTF font file relative to the TTF_FONT_DIR (that you set in step 5 above). For example, if TTF_FONT_DIR='C:\OS2\FONTS', and TTF_FONT="ARIAL", then C:\OS2\FONTS\ARIAL.TTF file will be used. Colors used for TTF_FONTS will be set by the TEXTCOLOR and BACKCOLOR options. However, by using color slides you can greatly increase the visual appeal of the your GIF_TEXT images. For a variety of reasons, messages written with a TTF font are NOT done a "character at a time". Thus, the "character scaling" rules will NOT apply to each character in the message. Notes: * If both a TTF font, and an "alphabyte or complete" font are specified, the TTF font will be used. * If TTF_FONT is specified, but TTF_FONT_SIZE is not (or if TTF_FONT_SIZE=0), then the TTF font will NOT be used (instead, the value of FONT will be used).. II.b.2----------------- Recommended WIDTH: The width, in pixels, of the image. Example: Width=480 The image will be scaled to fit into WIDTH pixels. If you do not specify WIDTH, or if you set WIDTH=0, then GIF_TEXT will use all the pixels required). Notes: * this overrides the default WIDTH variable (in GIF_TEXT.CMD) * width will include X_FRAME (thus, writeable area is width-2*X_FRAME) HEIGHT: The height, in pixels, of the image. Example: height=60 The image will be scaled to fit into WIDTH pixels. If you do not specify HEIGHT, or if you set WIDTH=0, then GIF_TEXT will use all the pixels required. Note: * this overrides the default HEIGHT variable (in GIF_TEXT.CMD) * height iwll include Y_FRAME (thus, writeable area is height-2*Y_FRAME) II.b.3----------------- Often useful AS: The file to save the GIF image to. This is ONLY used in a parameter list included in a command-line invocation of GIF_TEXT. For example: D:\APPS>gif_text text=hi font=hobo as=hello1.gif TIME_FMT: The format used to display the time. Example: time_Fmt='N' GIF_TEXT understands several "REXX" time formats. They are: L : Long (for example: 16:54:22.12000) N : 24 hour (16:54:22) H : Hour (16) M : Minutes (1014) S : Seconds (60682) C : Civil (4:54pm) 1 : Same as C, with special am and pm characters used (if available) Note: this overrides the default TIME_FMT variable (in GIF_TEXT.CMD) DATE_FMT: The format used to display the date. Example: time_Fmt='E' GIF_TEXT understands several "REXX" date formats. They are: N: Internet standard (for example: 27 Aug 1988) D: Days (240) E: European (27/08/88) M: Month (August) B: Basedate (725975) O: Ordered (88/08/27) S: Sorted (19880827) U: US (08/27/88) W: Weekday (Saturday) Note: this overrides the default DATE_FMT variable (in GIF_TEXT.CMD) BACK: The name of .GIF file to use as a background for the text message. It should be a filename relative to the GIF_DIR_ROOT directory. Example: BACK="BACKS/SATIN.GIF" Notes: * By default, no background is used * BACK=0 means "no background" * When BACK is set, then BACKCOLOR is ignored. SPECIAL OPTION: if GIF_Text is being run as an SRE-http addon, then you can specify a fully-qualified URL pointing to a .GIF file. GIF_Text will attempt to retrieve this .GIF file and use it as a background. Variant: BACK2 means the same, and will override, BACK. BACK_SCALE: If BACK_SCALE=1, then the background will be scaled to fit into the message area. Otherwise (by default) the background image will be "tiled" into the message area. X_F: The size, in pixels, of the left and right frame. or This is designed to be used with the WIDTH option. X_FRAME It is most useful when combined with a background, especially a "button" background". Note: the width of the text will be WIDTH-(2*X_F). Y_F: The size, in pixels, of the top and bottom frame. or is designed to be used with the HEIGHT option. Y_FRAME It is most useful when combined with a background, especially a "button" background". Note: the height of the text will be HEIGHT-(2*Y_F). X_OF Move the image this many pixels to the right (or left, if or X_OF is negative. If large values are used, portions of X_OFFSET the image will be cutoff (they'll be outside of the frame of the image). Y_OF Move the image this many pixels down (or up, if or X_OF is negative. If large values are used, portions of Y_OFFSET the image will be cutoff (they'll be outside of the frame of the image). Hint: you can use the X and Y offsets to create a "shadow" of your text image. To do this: a) create a .GIF image of a text string, with a small (say, 10) offset; and using a bland color slide b) save this image to a file in your GIF_DIR_ROOT directory c) regenerate the image, using: i) the image created in b) as background file ii) 0 offsets iii) using no, or a different, color slide Y_VAL: Vertical alignment. By default, characters are aligned at or the top of the image (after adding a y_frame); pr at Y_VALIGN the top or bottom of "line's image" (of a multi-lines-of-text image). You can choose to align at the bottom, or in the middle: Y_VAL=T -- top of image Y_VAL=M -- middle of image Y_VAL=B -- bottom of image LINE_JUST : Type of line justification. Can be L,C, or R or (left, right or center); with L the default. JUSTIFY Only used on multiple line messages (where $n is used to specify a "new line". LINE_SEP : Spacing between lines (of a multi-line message), in pixels. The default value is 2. The next several options, dealing with scales and slides, are used to produce fancy transforms of your characters: including in-message variations in character size, and color transformations. The color transformations are especially handy when used with black and white fonts (such as the "complete" fonts one might derive from a ttf or ps font). X_SCA: A space delimited list of "width scale factors", used to or adjust the width of each character of the message. X_SCALE This list should contain numbers, where 1.0 means do not adjust width, <1.0 means shrink, and >1.0 means increase. Width adjustment works by mapping the nth character of the message to the this list, with fractional mappings resolved by interpolating between list components. Example: X_SCA=1.0+1.2+1.5+1.1 (note use of + to signfiy space) In this example, the first character will be regular size, increasing until 2/3 through the message (where the adjustment is a 50% increase), and then decreasing to a 10% increase at the last character Y_SCA: Same as X_SCA, but for character height or Example: Y_SCA=0.5+1.0+2.0 Y_SCALE Start at 1/2 size and end at double size. Color slides are used to transform the color of each pixel in the message image. Basically, if the value of a pixel in the "message image" exceeds some threshold, then an appropriate color in the "color slide" is displayed (instead of the color specified in the "message image"). Execution note: Although color slides are a very convenient way of converting a simple (black and white) "complete font" into a colorful font, they do require some time to execute -- say, 20 seconds to process a 300x50 image (on a Pentium 100). SLIDE : The name of slide file. Slide files are simply images that are used to transform the colors of the message. In it's simplest use: If the pixel value of the message image is greater then 1, Then the color of the corresponding pixel, in the slide, will be used. The "corresponding pixel" is a function of pixel position, both horizontally and vertically -- see the SLIDE_H, SLIDE_T, and the other SLIDE_ options for details! Note: When specified in the selector, relative slide files should be .GIF files located relative to the ALPHABYT directory. For example, slide=slides/rainbow.gif (might) be in the D:\GOSERVE\ALPHABYTE\SLIDES\RAINBOW.GIF directory. Note: When specified in a font index file, relative SLIDE files are assumed to be relative to the font's own directory. example: slide=slides/rainbow2.gif (note that / is converted to \) SPECIAL OPTION: if GIF_Text is being run as an SRE-http addon, then you can specify a fully-qualified URL pointing to a .GIF file. GIF_Text will attempt to retrieve this .GIF file and use it as a color slide. SLIDE_S : Size of user created color slide. SLIDE_S (and SLIDE_B, SLIDE_G, and SLIDE_R) are IGNORED if SLIDE is specified (and the .GIF file that SLIDE points to exists). SLIDE_H : Horizontal slide type. Two types are recognized: T = Tile. If the image is wider then the slide, then repeat the slide (i.e.; horizonatally concatenate it) F = Fit. If the image is wider then the slide, then stretch the slide (i.e.; create runs). If the slide is wider then the image, then pick equidistant pixels from the slide, with the first (last) pixel in the slide used for the first (last) pixel of the image (that is, fit image to slide). example:slide_h=T Note: the default value is F SLIDE_V : Vertical slide type. Three types are recognized: T = Tile F = Fit N = Just use one row (in the middle third of the image) If the slide is just one row high, then this option is ignored (the first row is always used). Example: slide_v=F SLIDE_T : Slide threshold. A two component answer: tnnn; where type is the type, and nnn is an integer between 0 and 255. Type can be P,B,C. P : If pixel value is >=nnn, use slide B : If average of the 3 color values is >= nnn, use slide C : If any one of the 3 color values is >=nnn, use slide Examples: slide_t=P1 (this is the default) slide_t=C100 Note: for a typical black and white alphabyte,, such as a "ttf derived" complete font, you should use slide_t=P1 Special usage of SLIDE_T -- you can specify a colon delimited list of thresholds; the threshold used will be drawn from this list, with interpolation (i.e.; in the same way that X_SCALE is interpolated). For example: SLIDE_T=P1:2:5 means the threshold starts at 1, goes to 2 for the middle width, and ends at 5. Note: it is probably NOT wise to use this "pixel specific" threshold with B/W fonts. SLIDE_C : Coordinates to use when computing slide position. A space delimited pair of numbers, each number can be a fraction between 0 and 1 (inclusive). By default, the "column" (the width pixel value) in the message image is used when looking up a color slide value. However, you can use a "pixel distance" from some user defined center. The effect is to create a 2d color wash, radiating out from this center. Note that the SLIDE_C coordinates are defined as a fraction of width and height; thus 0 0 is the uppe left corner, 1 0 is the upper right corner, and 0 1 is the lower left corner. Example: SLIDE_C=0.5+0.1 (center is near the top, at the horizontal center) FIGDIST_T : Method of computing distances for use with color slides. Four methods are supported: 1 : Linear distance. dist= sqrt(dx*dx + dy*dy). 2 : Box-steps. dist = abs(dx)+abs(dy) 3 : Modified box-steps. dist= max(abs(dx),abs(dy)) + min(abs(dx),abs(dy))/2 4 : 1 dimensional: dist=max(abs(dx),abs(dy)) where dx and dy are the "x" and "y" offsets (from a given pixel to a reference point). Method 1 tends to yields smoothest results, but can be quite slow (especially if you do not have REXXLIB.DLL). Method 2 and method 4 are similar, and are the fastest (about 10 times faster then method 1). Method 3 is an approximation to method 1, and is almost as fast as methods 2 and 4. We recommend method 3. However, you might want to experiment: in some cases, the results of using different methods can be quite different (this is most likely to occur when you specify SLIDE_C). Example: FIGDIST_T=3 SLIDE_P: Probability of using the color slide's value. This should be a space delimited list of fractions (between 0.0 and 1.0, inclusive). A value of 0 means "use the alphabyte's color", a value of 1 means "use the color slide's color". Example: SLIDE_P=1+1+0.9+0.2+0+0 First third of image is color slide, last third is image, middle third is a mixture. Note that + are used as "space parameters"; when SLIDE_P is entered in a font index file, use spaces between the values. SLIDE_P is meant to provide a simple means of creating a foreground fade-into effect: between the alphabyte's image and the color slides's image. Creation and use of in-between colors might look better, but with a 256 color limit per .GIF file, it might not. SLIDE_SI: Size of "user specified color slide" (# pixels and # colors) Instead of using a color slide contained in a file, you can "create" your own. SLIDE_SI should equal the size (in colors, hence in pixels) of this slide. For example: SLIDE_SI=50 ; a 50 element color slide will be used (based on SLIDE_RE, SLIDE_GR, and SLIDE_BL) Setting SLIDE_SI=0 (the default) suppresses this option. SLIDE_RE: Red color parameters for "created slide". Enter a list of 0 to 1 fractions; with 0 meaning "none of this color", and 1 "max intensity of this color". For example: SLIDE_RE=0.0+0.2+0.3+0.9+0.1 the red intensity will increase, then suddenly drop off. Note that SLIDE_GR and SLIDE_BL are specified in the same manner. SLIDE_GR: Green color parameters for "created slide" SLIDE_BL: Blue color parameters for "created slide" Mask files are used to mask the final image (the final image contains the background, the text characters, and the color slide modifications of the text characters. Mask files are simply .GIF files that are interpreted as "mask" -- with "masked" elements set to a pixel value of 0 (i.e.; to the transparent pixel). This can be used to create some interesting effects. MASK_FILE: Name of a mask file. This should be a .GIF file in (or relative to) the GIF_DIR_ROOT directory SPECIAL OPTION: if GIF_Text is being run as an SRE-http addon, then you can specify a fully-qualified URL pointing to a .GIF file. GIF_Text will attempt to retrieve this .GIF file and use it as a mask file. Examples: MASK_FILE=circle.gif MASK_FILE=http://foo.bar.net/shapes/triangle.gif MASK_THRESHOLD: By default, a value of 0 is used as a threshold. Use MASK_THRESHOLD (set to a non-zero value) to change this. Example: MASK_THRESHOLD=3 MASK_REVERSE: By default, pixels in the final image with values less than of equal to the MASK_THRESHOLD will be transformed to 0 valued pixels. You can use MASK_REVERSE to switch this (pixels greater then MASK_THRESHOLD will be transformed). Example: MAXK_SCALE=Y MASK_SCALE: As with color slides and backgrounds, you can either scale the mask file to fit the image you've created, or you can tile the mask file over the image. Example: MASK_SCALE=Y II.b.4 --------------- Less frequently used FONT_NAME: The "name" of the alphabyte font. or Example: FONT_NAME='ENVIRO' NAME The FONT_NAME is used when resolving .GIF filenames. This parameter is NOT required when using the alphabytes shipped with GIF_TEXT. See the "technical notes" section for details on how and when to use FONT_NAME. FONT_INDEX: The "index file" for the alphabyte font. or Example: FONT_INDEX='ENVIRO.IND' INDEX The FONT_INDEX contains alphabyte explicit information, including character to .GIF file assignations. If not included, GIF_TEXT will look for a FONT.ind file (in the FONT sub-directory of the GIF_DIR_ROOT directory). This parameter is NOT required when using the alphabytes shipped with GIF_TEXT. See the "technical notes" and "Sample of a FONT_INDEX" sections of this document for further details on how and when to use a FONT_INDEX. CACHE: The name of a file (in the GIF_DIR_ROOT directory) to use to store the created image. If the "image cache" is enabled (see the technical notes), then the image cache is first searched for this file. If it exists (and is still valid), it will be used. If it does not exist, the image will be saved to this file "for future use". See the technical notes below for details. Note: if a $t or $d occurs in the message, CACHE is ignored! CACHE2: Same as CACHE, but $t and $d do NOT suppress use of the cache (note that the time and date will NOT be updated)! BACKC: The background RGB colors. or Example: BACKC=98AE10 BACKCOLOR A 6-hex-character color code used to define the background color. This will override the DEF_BACKCOLOR variable (in GIF_TEXT.CMD) In addition, it will override the BACK= parameter in the FONT_INDEX. Note that if a BACKground file is used, BACKCOLOR is not used. TEXTC: The default-font RGB colors or Example: TEXTCOLOR=FF220 TEXTCOLOR A 6-hex-character color code used to define the default-text color. This will override the DEF_TEXTCOLOR variable (in GIF_TEXT.CMD) In addition, it will override the TEXT= parameter in the FONT_INDEX. TRANS: The index of the transparent color. Example: TRANSPARENT=0 Should be a value between 0 and 255. A value of -1 means "no transparent color". This will override the DEF_TRANSPARENT variable (in GIF_TEXT.CMD) LITERAL: Set to 1 to supress $n code interpretation in the text. Example LITERAL=1 SEND: Set to 1 to "send pieces of the image as they become available, 0 to send entire image when done. This overrides the SEND_PIECES argument in GIF_TEXT.CMD Note that "sending pieces" only works with browsers that can handle multi-part documnets (such as Netscape 1.3, but not IBM Web Explorer 1.1) MANY_C : MANY_C has two uses: 1) If equal to CYCLE FIT END or RANDOM: overrides the MANY_COMPLETE setting in the FONT_INDEX. 2) If equal to a number > 0: sets the "number of fonts" to use. This is useful if you only want to use the first 2 (or 1, or 3, or ...) of a many-font set. See section IV.a for details Note: when running GIF_TEXT in "stand alone" mode, you will be explicitly asked to provide values for several of these options. You will also be given the opportunity to enter "additional options" -- in which case you should use the syntax specified above (i.e.; as if the options were part of an http request). Note that stand-alone mode has a bit of on-line help, and it will save prior answers in a GIF_TEXT.ANS file. ----------------------------------- III. Technical notes GIF_TEXT roughly takes the following steps when considering a request. Note that the values of the parameters may be a generic default (as set in GIF_TEXT.CMD), may be from the font index file, or may be supplied as one of the request options. 1) Determine the size of the image 2) Create a background 3) Determine locations of characters a) Use a character specific .GIF file if avaialable b) Use a "complete font" file if available c) If neither a or b are satisified, use the built in font Section IIIa describes this step in greater detail. 4) IF X_SCALE or Y_SCALE are specified, stretch (or shrink) the image associated with each character 5) Create a message image using results from step 4 6) If a color slide is specified, transform the appropriate pixels in the "message image". Section IIIh contains details. 7) Write the message image on top of the background 8) If a mask was specified, use the mask to set foreground pixels to the background "color" 9) Transfer the results. IIIa. Basic File Matching Algorithim When using "alphabyte" fonts, with one font per character, GIF_TEXT has to determine what the appropriate .GIF file is. For purposes of illustration, let's assume two examples: i) <IMG src="/GIF_TEXT?font=HOBO&message=Welcome!"> ii) <IMG src="/GIF_TEXT?font=NEWFONTS\FONT1&message=Welcome+(today)"> and a GIF_DIR_ROOT='D:\GOSERVE\ALPHABYT' (as set in GIF_TEXT.CMD). Furthermore, assume that you've correctly installed the various .GIF and .IND files be in the appropriate FONT= directories of the GIF_DIR_ROOT. In our examples, these directories are: i) D:\GOSERVE\ALPHABYT\HOBO\ ii) D:\GOSERVE\ALPHABYT\NEWFONTS\FONT1\ The following outlines the logic used by GIF_TEXT when matching a .GIF file to a character. 1) A FONT_INDEX file (in this directory) will be examined for explicit "character to .GIF file" assignations. If you did not define a FONT_INDEX, then an "ownname.ind" file is looked for. In our examples, the following index files are looked for: i) D:\GOSERVE\ALPHABYT\HOBO\HOBO.IND ii) D:\GOSERVE\ALPHABYT\NEWFONTS\FONT1\FONT1.IND If the desired character is listed in the FONT_INDEX, and the file this listing refers to exists, then this "refered to file" is used. For example, an entry in the FONT_INDEX of: # NUM.GIF means "use NUM.GIF for the # character". Or, either ##224 ALPHA.GIF ##E0x ALPHA.GIF means "use ALPHA.GIF if the characters ascii value is 224" (note that the latter syntax is the hex value of 224). Caution: If you are using MKGIFTXT.HTM -- be aware that the "ascii" value sent by a browser (using #hh syntax) depends on the code page used by the browser). For "high ascii" characters, you might want to instruct users to use $#nnn; or $#nnx; sequences. In addition, the FONT_INDEX can contain information on which (if any) "complete" font to use as an "alphabyte specific default". For details on how to structure a FONT_INDEX file, see the "Sample of a FONT_INDEX" section of this document. For details on "Complete" fonts, see the Complete Fonts section of this document. 2) If no match in the FONT_INDEX can be found, then look for the following file names. a) For lower case characters only a1) Look for xLC.GIF a2) Look for FONTNAMExLC.GIF a3) Look for FONTNAME-xLC.GIF b) For all characters: b1) Look for x.GIF b2) Look for FONTNAMEx.GIF b3) Look for FONTNAME-x.GIF b4) Look for xFONTNAME.GIF .... where x is the desired character, and FONTNAME is the name of the desired font. 3) If 1 and 2 do not yield a match, then generate a font using either: a) the "alphabyte specific complete" font, or b) the the rudimentary font built into GIF_TEXT. In either case ,the TEXTCOLOR variable can be used as the color of the message-text. Note that TEXTCOLOR can come from (in order of precedence): a) A TEXTCOLOR= option (in the src="...") b) A TEXT= entry in the FONT_INDEX file c) The value of the DEF_TEXTCOLOR variable (in GIF_TEXT.CMD). (see section IIId for details on "alphabyte specific complete" fonts). Example: If the "x" character of the HOBO alphabyte is desired, and there is no match in HOBO.IND, the following will be looked for (the first successful match is used): a) D:\GOSERVE\ALPHABYT\HOBO\XLC.GIF b) D:\GOSERVE\ALPHABYT\HOBO\HOBOXLC.GIF c) D:\GOSERVE\ALPHABYT\HOBO\HOBO-XLC.GIF d) D:\GOSERVE\ALPHABYT\HOBO\X.GIF e) D:\GOSERVE\ALPHABYT\HOBO\HOBOX.GIF f) D:\GOSERVE\ALPHABYT\HOBO\HOBO-X.GIF g) D:\GOSERVE\ALPHABYT\HOBO\XHOBO.GIF Notes: * for non-english alphabytes (i.e.; alphabytes containing umlaut, acutes, and other such characters); you might need to specify $nn or ##nnn entries in the FONT_INDEX file. * for non lower case characters, steps a,b and c are skipped. * if you've obtained a font with a prefix that does not match it's "name", you should include a FONTNAME option. For example, for <IMG src="/GIF_TEXT?font=HOBO&message=Welcome!"&FONTNAME=SLICK> instead of HOBO\HOBOXLC.GIF, GIF_TEXT would look for HOBO\SLICKXLC.GIF, etc. In addition, if INDEX is not specified, GIF_TEXT will look for SLICK.IND as an index file. * Reminder: OS/2 does NOT differentiate between upper and lower case when searching for a filename. ---------------- IIIb. Adding an alphabyte To add an alphabyte: 1) Create a new subdirectory under the GIF_DIR_ROOT 2) Copy the .GIF files (1 per character) to this subdirectory. 3) You might need to rename the .GIF files to adhere to the logic discussed in section IIIa. In general, unless you really need to, it's simpler to NOT specify the FONT_INDEX and FONT_NAME when invoking GIF_TEXT (just make sure you've approriately named the alphabyte, etc. files). 4) Create a FONT_INDEX file. The font_index file should always contain the BACK= (background) and TEXT= (textcolor) arguments. You can also include: * Special "character to GIF file" mappings (such as for punctuation marks, or high-ascii characters). * Special entries (to match $nn substrings, such as $1 and $2 for the AM and PM "characters"). * An alphabyte-specific "complete font" to use as a default. 4a) For "complete fonts" that stand by themselves (such as those derived from ttf or ps fonts), there will be NO "character specific GIF files", and the FONT_INDEX file is REQUIRED! 5) If you find renaming files to be tedious, and the names of the alphabyte .GIF files do not conform to the rules discusssed above, you can include "character specific filenames" in the FONT_INDEX file. 6) You can specify special characters ($n) in the FONT_INDEX file (see section IV for details). ---------------- IIIc. Adding a background Adding a background is as simple as finding a .GIF file (say, a texture) that you like, and copying it to some directory relative to the GIF_DIR_ROOT directory (say; d:\goserve\alphabyt\backs). You might want to reduce the color table of the background (remember, a .GIF file can only have 256 colors), but you don't have to. Reminder: When specifying the background, be sure to include the subdirectory (relative to the GIF_DIR_ROOT dir). For example: back=backs/my_back.gif where backs is a subdirectory of GIF_DIR_ROOT ---------------- IIId. Adding a complete font As an alternative to the use of "one file per character" alphabytes, GIF_TEXT can also use "complete" fonts. By "complete" fonts, we refer to a .GIF file that contains a "grid" of fonts arranged in equi-sized cells. In addition to allowing one to use "regularly spaced" fonts delivered in one file, complete fonts can be a convenient way to make use of postscript and true type fonts. Note: Various programs (GhostScript for PS fonts, THUMBSPLUS for TTF fonts, etc.) can display the various characters that comprise a (PS, TTF, etc.)font. Typically, the characters will be displayed in a "grid", with each cell of the "grid" the same size. With a little bit of work, a .GIF file containing such a "grid" can be used as a "complete font". That is, instead of looking for a file that matches a character, GIF_TEXT can extract the image of the character from a (single) .GIF file that contains a "complete set of fonts". In order to do this, you must provide some information in a FONT_INDEX (an .IND) file. a) The name of the .GIF file that contains the complete font b) A "black and white" flag c) the x,y offset (in pixels) to the upper left corner of the first character d) the number of characters in a row e) the width and height of each character (in pixels) f) the "within grid cell" offset (left, top, right, bottom) g) a list of the characters, in order of appearance. h) Optional: text color, transparency, and background color information. In general, you would create a seperate directory for a "complete" font that would contain just the .GIF and the .IND file (the FONT_INDEX). Perhaps of greater use, you can combine a standard (1 file per character) alphabyte with a complete font -- the "complete" font will be used if no matching "alphabyte" file can be found. To do this, just add the items mentioned above to the alphabyte's FONT_INDEX (the .IND file); and make sure the "complete font" .GIF file is in the same directory as the "single character" .GIF files (of this alphabyte). Notes: * For details on what to include in the .IND file, see section IV below. * You may find EXT_GIF.CMD, a simple utility included with GIF_TEXT, useful. It can be used to extract all the "character" .GIF files from a complete font. This can be useful for: ** verifying the .IND file (say, in conjunction with PMVIEW's thumbnail feature) ** if you want to modify each font (say, to create a 1-file-per-character alphabyte). ---------------- IIIe. Adding a TTF font To add a TTF font, simply copy the TTF font file to the TTF_ROOT_DIR. No further set up is required. Be sure to copy the TTF font, and not a ZIPped version of the font! Alternatively, you can create subdirectories under TTF_ROOT_DIR. If you adopt this approach, be sure to include the subdirectory name (in addition to the font file name) when specifying a TTF_FONT option. Lastly, when run under SRE-http, you can GET a ttf font off of the WWW -- just specify it's URL (make SURE to include the http://). ---------------- IIIf. Caching Images When using GIF_TEXT to create static in-line images (that do not contain $t or $d, and that are not created by MKGIFTXT or some other FORM based front end), it is likely that the same image will be recreated repetitively. Of course, you can be sensible and create the image once (say, with MKGIFTXT), save it, and include this saved image explicitily. But if you are sort of lazy, and have a powerful enough machine, you can use the GIF_TEXT cache to "save the images for you". To do this, you have to do two things: 1) In GIF_TEXT.CMD: Set the values of the CACHE_DURATION and CACHE_SIZE variables. * CACHE_DURATION sets the lifespan of a "saved image" (in days). If you might modify the "alphabytes", set this to be a low value. Example: CACHE_DURATION=2 * CACHE_SIZE sets the maximum number of "saved images" to retain. If you are worried that hackers might "save" a lot of images on your site, set this to a low number. Note that once the CACHE_SIZE files appear in the GIF_DIR_ROOT directory, caching is suppressed -- there is no attempt to "intelligently" weed out older or less used entries. Example: CACHE_SIZE=150 2) Include a CACHE=filename.GIF option in your <IMG Src="/GIF_TEXT?.."> element. Alternatively, use a CACHE2=filename.GIF. CACHE2 will "force caching", even if a $t (time) or $d (date) "special code" appears in the message. Example: <IMG SRC="/GIF_TEXT?font=revue&text=Welcome!&cache=WELCOME1.GIF"> * In this example: If "WELCOME1.GIF" exists, it will be used. Otherwise, GIF_TEXT will generate the image, send it to the client, and thant save the image to WELCOME1.GIF for future use. Notes: * to supress caching, set CACHE_SIZE=0 * If you do not include a CACHE= option, the cache is ignored. * filename.GIF should be a UNIQUE filename -- !!! It is YOUR responsibility to NOT use the same !!! name for different in-line images. * filename should NOT contain path information -- it will refer to files in the GIF_DIR_ROOT directory. WARNING: Since use of the cache requires invocation of GIF_TEXT, rather then mere transferal of a file, we don't generally recommend it -- on a low-powered server, it can be slow. Furthermore, there is some concern with stability -- on occassion, when RXGDUTIL procedures are rapidly called, (as will happen if a single document contains requests for several "cached" images) server errors may occur (such as the infamous SYS3175). HINT: One good use of the CACHE option is to save an image for later downloading (a trick used by MKGIFTXT.CMD). IIIg. Using GIF_TEXT as a counter Although not the most efficient method of generating a graphical "hit counter", GIF_TEXT does provide a fairly powerful graphical counter. However, you will need a server that can generate a textual "count of hits" as a "server side include". For example, users of the SRE-http WWW server can use: i)  or ii)  Example of a "random colors" counter, using the COUNTER.RXX facility: <img src="/cgi-bin/gif_text?font=bck&back=backs/tan&text=&height=50&width=100&x_f=2&y_f=2" alt="hit counter"> A more traditional example, using a frameless auto style odometer, and SRE-http's REPLACE COUNT: <img src="/cgi-bin/gif_text?font=57chevy&text=" alt=""> III.h) Using color slides. Color slides are simple and effective means of making drab fonts come alive with color. The notion is to create a "message image" using your favorite alphabyte (or complete font), and then use "foreground" colors drawn from the color slide instead of the colors the font was created with. This is especially useful when used with black and white fonts, such as "complete fonts" derived from a ttf or ps font. At it's simplest, a color slide is a one row .GIF file with some sort of rainbow or similar color pattern. For each row of the "message image" (the image formed from writing the appropriate alphabyte characters), a column-by-column mapping, between the pixel in the message image and the pixel in the color slide, is performed. If a pixel's value is above a threshold (i.e.; greater then 0), then the color from the color slide will be used. Thus, a pixel on the left size of the image will be displayed with a different color then a pixel (with the same value) on the right side of the image. There are two ways of specifying a color slide: 1) By selecting a .GIF file to use as a color slide. GIF_TEXT comes with a dozen or so examples of color-slide files. 2) By specifying a set of RGB parameters. The SLIDE_S (and SLIDE_R, SLIDE_G, and SLIDE_B) can be used to specify a color slide). Once specified, there are 3 ways the color slide can be used 1) As a single row (column specific) transformer 2) As a "color wash" (or color gradient) centered at a point defined by the SLIDE_C option. 3) As a 2 dimensional foreground image. In all cases, it is unlikely that the size (either height or width) will be the same as the size of the message image. To fit these mismatched sizes, you can either repeat the color slide, or you can stretch it -- the SLIDE_V and SLIDE_H control this fit method. Note that when the color slide is used as "single row", a multi-row GIF file can still be used, GIF_TEXT will use a row 1/3 of the way down from the top. Please be aware that to use a multi-row color slide as a single row, you must set SLIDE_V=N. Selection of which message image pixels to transform is based on the pixel's value, on the SLIDE_T option, and on the SLIDE_P option. Selection is usually based on the pixel's value, which ranges between 0 and 255 (i.e.; in b/w images, background pixels typically have a a value of 0, and foreground pixels have a value of 1). However, the average color brightness of the pixel, or it's maximum color brightness can be used. Furthermore, this threshold can depend on the position in the image of the pixel. You can also use the SLIDE_P option to create a fade-into effect, with the color slide colors being used at the start of an image, the alphabyte colors used at the end, and a mixture used in between. III.i) Switching fonts You can use the $F(fontname) "special code" to tell gif_text to start using the "fontname" font. This can be used to create fairly complicated mixed-font messages (it's a more flexibile alternative to the "multiple variants of a font" option discussed below). Be aware that the switched-to font may have slightly "wrong" characteristics. For example, "complete fonts" may be displayed using the color associated with the message's "original" font. Also note that the fontname must be a "standard" GIF_TEXT font. That is, it must point to a font in a subdirectory of your alphabytes directory, and this subdirectory should contain a fontname.ind file. For example, if fontname is "HOBO", then the HOBO/ and HOBO/HOBO.IND, will be used. In other words, the fontname is use for the FONT_NAME, FONT_INDEX, and FONT_DIR variables. Alternatively, you can switch to a TTF font. To do this, the "fontname" should have the following structure: !nn_ttfname where nn = point size ttfname = name of the ttf file (without the .TTF extension) For example: message="Courier and $f(!28_couri) 28 point italic." ----------------------------------- IV. Sample of a FONT_INDEX The notion is that GIF_TEXT has defaults (declared in GIF_TEXT.CMD) that are overridden on a font-specific basis by entries in the font's "index" file Note: You can override these font-specific defaults on a request specific basis by including the appropriate options in the request to the server. In general, most of the "request line options" can be specified in a FONT_INDEX. Thus, for a complete description of what the parameters do, either check the descriptions in the "options" above, or look at the sample below. Note that several of these parameters expect a space delimited list. In the description above (as request line options), a + is used as a space -- a requirement of the http method of forming requests. However, when specified in an index file, you can use a space (that is, use a space instead of a + character). The following illustrates and describes FONT_INDEX files. Note that blank lines are ignored, and that lines starting with ** are comments. List of FONT_INDEX parameters: TEXT=aabbcc : Default text color BACK=aabbcc : Default background color x filename.gif : Match character "x" to an explicit gif file ##nnn filename.gif : Match character with an ascii value of nnn to an explicit gif file ##nnx filename.gif : Match character with an ascii value of nn (hex) to an explicit gif file char=n filename.gif : Match a $n (or $nn) substring to an explicit gif file x_scale=n.n m.m j.j : Space delimited list "character specific width scales" y_scale=n.n m.m j.j : Space delimited list "character specific height scales" y_valign=T/M/B : How to vertically align characters slide=filename.gif : An (optional) color slide file. slide_h =T/F : Tile or Fit color slide to image (horizontal) slide_v =T/N/F : Tile, Fit, or one row of color slide to image (vertical) slide_t =P/C/An:n2:n3 : Threshold: (pixel, one color, or average color) slide_p =v1 v2 v3 : Probability of using slide parameters slide_s =n : size of user specified color slide (0=none) slide_r =v1 v2 v3 : Red parameters for user specified color slide slide_g =v1 v2 v3 : Green parameters " " " " " slide_b =v1 v2 v3 : Blue parameters " " " " " (the following parameters are used to describe a "complete font": complete=filename.gif : File containing a "complete "font. More then one complete= may appear. Note: for downward compatability, you can also use defaults=filename.gif def_chars=abcd e : List of characters (must match list of characters in the complete font file). When specifying a "complete" font, this is REQUIRED. def_bw=0/1 : Complete Font is a black & white font (if so, use TEXT and BACK colors) def_offset=xoff yoff : Pixel offset to top-left of first character (in a complete font file) def_inrow : # characters per row def_charsize=width height : Character size (width and height) def_char_offset=l t r b : Additional offset, within character (gets rid of white space) -------- Beginning of Sample .IND file ----- ** FONT_INDEX files are used to: ** 1) set explicit character-to-file matches, ** 2) set the text-color and other defaults ** 3) to identify special "characters". ** 4) information on the "alphabyte specific complete" font. ** 1a) Text-color-defaults ** Start the line with a TEXT=, and then immediately thereafter put in the ** 6 hex character color code ** i.e. 6200bb (a reddish blue) TEXT=60f0ff ** 1b) Background color-defaults ** Similar to 1a, but start the line with BACK= BACK=633332 ** 1c) A "transparent" color-index that is used when a background is being used. transparent=0 ** 2) Character-to-file matches ** Each entry should contain the character (case sensitive), followed by the ** file name (relative to the font_dir directory -- do NOT use a fully ** qualified name) - DASH.GIF ' APOS.GIF ! EXC.GIF : COLON.GIF & AMP.GIF ? QUEST.GIF AM AM.GIF PM PM.GIF ** characters with an "ascii" value of 225 use BETA.GIF ##225 Beta.gif ** Same as above, but expressed in hex ** Note: using hex, it's easier to match browser mappings, of FORM inputs, to desired characters. ##e1x Beta.gif ** Note special "AM" and "PM" entries -- these are ONLY used by ** the $T "time of day" special character ** Note that for characters not included in this file, the ** default naming conventions will be used (see section III.a for details) ** 3) Identifying special characters ** GIF_TEXT interprets $n substrings (in the message),with n some digit, to mean ** "use special character # n". You can define these "special characters" ** here by using ** CHAR=n file.gif ** For example, if you have a special PM character, you could define ** CHAR=1 pm.gif ** and if the message contains $1, then the PM.GIF "character" will be ** inserted (if PM.GIF is not available, the $1 will be ignored) ** Note: n must be between 0 and 99 CHAR=1 pm.gif CHAR=2 am.gif char=10 lquote.gif char=11 rquote.gif ** Note that 1 (PM.GIF) and 2 (AM.GIF) may (or may not) be different ** then the AM.GIF and PM.GIF "character to file" matches. ** 4) Information on the alphabyte-specific complete font ** Complete fonts are .GIF files that contain all the characters. These characters ** must be arranged in a grid, with each cell of the grid the same size. ** Complete fonts are used whenever there is is no matching "alphabyte" (.GIF) ** file for a character ** (in many cases, you may not have ANY "alphabyte" files, you'll ** only have the "complete" font file). ** ** In order to use a complete font, you must specify several parameters: ** a) The .GIF file (in the same directory as this .IND file) that contains ** the complete font complete=handwrit.gif ** (note, defaults= is synonymous with complete=) ** b) Is this a black and white font? (0=no, 1=yes). ** If 1, then text= and back= colors are used. ** Use 1 if you have a black and white font (say, as derived from ** a screen dump of a .ttf font). ** If 0, then the palette (in the .GIF file) is used as is. ** Use 0 if you have a multi-colored "complete font" def_bw=1 ** c) the x (column) and y (row) PIXEL offset in the .gif file -- ** to the upper left corner of the first character (the first column of ** the first row of the "grid" of characters) def_offset=0 47 ** d) the number of characters in a row (that is, the number of columns in the grid) def_inrow=16 ** e) the width and height of each character, in pixels def_charsize=46 47 ** f) The within-character offset. If a lot of white space is placed around ** each character's "grid cell", you can offset the portion used. ** 4 values are required: a left, top, right, and bottom offset. This ** can be used to tighten up the placement of characters in the message. def_char_offset=0 0 0 0 ** g) The characters, in order of appearance. REQUIRED. ** Spaces should be used for "empty or unneeded" characters ** If this gets out of order, incorrect characters will be written! ** A first space (after the =) is important -- since the row=1 column=1 character ** is often (but not always) a space. def_chars= !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ ** ** 5) Fancy modifications ** X_SCALE (Y_SCALE) is use to shrink/expand the width (height) of each ** character in your message. A mapping of character position to ** the position in the X_SCALE (Y_SCALE) list, with linear interpolation, ** is used to determine the width (height) scale x_scale=1 1.3 1.6 1 y_scale=1 1.1 1 0.7 ** ** Y_VALIGN is used to vertially align each characters. Y_VALIGN ** can take 3 values: T=Top, M=Middle, and B=Bottom -------- End of Sample .IND file ----- IV.a) Special note: using multiple variants of a font in one message. If you have variants of a "complete font" that have the same dimensions, but may differ in style, color, etc.... you can use them to mix up the letters in a message. To do this, just specify multiple complete=xxx.gif lines. A list of complete fonts will be formed from all the "complete=..." lines found. For example, if you have: complete=Redwood.gif complete=Bluewood.gif complete=Grewood.gif then the letters will be displayed using characters from all three "wood" files. By default, the multiple "complete fonts" will be cycled through. For example, if the message is "hello", then h : drawn from Redwood.gif e : drawn from Bluewood.gif l : drawn from Grewood.gif l : drawn from Redwood.gif o : drawn from Bluewood.gif You can also set many_complete=type where type can be CYCLE, FIT, or END. CYCLE is the default, END will do a 1-to-1 match, with overflow message characters using the last complete font (i.e.; l,l, and o would all use Grewood.gif), and FIT would assign (approximately) equal number of character to each font; thus h is drawn from Redwood.gif, e and l from Bluewood.gif, and l and o from Grewood.gif RANDOM would randomly assign a character to a font (with a a different assignation on each request) Notes: * by "same dimension", we mean the same offset, inrow, charsize, etc. * The EPILOG2 "complete font", packaged with GIF_TEXT, is a simple example of a multiple variant font. * Instead of using these multiple variants, you might find that the use of $F(fontname) in a message is more flexible. IVb. An example of adding a new alphabyte. This is a step by step example of how to add a new alphabyte. For illustrative purposes, let's assume that your GIF_DIR_ROOT directory is D:\GOSERVE\ALPHABYT (if not, just appropriately substitute the correct directory in what follows). 1) Find the ZIPJAZ.ZIP file in the temporary directory into which you unzipped GIF_TEXT.ZIP. NOTE: The JAZ alphabyte was obtained from Carol's Clipart, which is now (alas) defunct. 2) Create a JAZ directory under D:\GOSERVE\ALPHABYT, and copy ZIPJAZ.ZIP to D:\GOSERVE\ALPHABYT\JAZ 3) UNZIP ZIPJAZ.ZIP (in D:\GOSERVE\ALPHABYT\JAZ directory) 4) You are now ready to produce some messages. For example http://your.server.org/gif_text?text=hello&font=jaz&mess.gif (the final mess.gif is a hack that some browsers require to succesfully display the image in-line). 5) Now try http://your.server.org/gif_text?text=123abc&font=jaz&mess.gif This won't look so good -- we need to specify some defaults. 6) Create a JAZ.IND file (in the JAZ subdirectory). It should contain the following lines ( do NOT include stuff in parenthesis): BACK=b0b0b0 (a bright grey) TEXT=00b0b0 (a bright cyan) TRANSPARENT=0 Now try http://your.server.org/gif_text?text=123abc&font=jaz&a.gif, it's not beautiful, but it's better. 7) Let's get ambitious, and add a "complete" font definition, which will be used as an alternate to the "generic" default. 7a) Copy D:\GOSERVE\ALPHABYT\BUTTRFLY\BUTTRFLY.GIF to the JAZ directory. 7b) Add the following to JAZ.IND complete=buttrfly.gif def_offset=0 47 def_charsize=48 47 def_inrow=16 def_bw=1 def_chars= !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^ `abcdefghijklmnopqrstuvwxyz{|} Again, try http://your.server.org/gif_text?text=123abc&font=jaz&a.gif, I'ld argue it's close to acceptable. ----------------------------------- V. Acknowledgments This utilty would not have been possible without the RXGD101 library -- the full package is available from http://www.bearsoft.com/abs/rexxgd.html; it's a port of the GD library, and is written by Andy Wysocki (awysocki@bearsoft.com). In addition, the RXTTF.DLL "ttf to bitmap" library was created by Michal Necasek (mike@mendelu.cz). ...and, it would have been useless without the various and sundry alphabyte fonts, etc. which were obtained from various sources, including: Rosie's Alphabytes http://www.geocities.com/HotSprings/3055/alphabet.html</a> E-Mom's Rainbow Graphic Designs: http://members.xoom.com/e_mom/ Andy's Art Attack: http://www.andyart.com Additional fonts can be found at a number of places. A very good source for mostly free fonts, many of them "complete fonts" (you'll need to spend a few minutes making an .IND file), can be found at Daniel Guildkrans site at http://www.algonet.se/~guld1/freefont.htm If you want to use GIF_TEXT as a clock or calendar, you will only need digits and a few special characters (such as the :, /, -, AM, and PM). A good source for such limited "digit sets" is http://www.digitmania.com. You can also find links to a few other sites at http://www.digitmania.com/alphabet.html. Note that several "complete-fonts" were created from true type fonts obtained from now defunct sources. However, you might want to try www.customeffects.com. TTF fonts can be found in many places, that tend to come and go. One nice site (circa April 1999) is http://fonts.tedesign.net Do you have questions, or do you have links to some additional alphabytes? Let me know: Daniel Hellerstein (danielh@econ.ag.gov)