Gauche-gd Reference Manual

For version 0.3.1

last update: Thu Mar 24 2011

http://www.fixedpoint.jp/gauche-gd/

C Layer API

class: <gd-image>

A fundamental class. Its instance has a foreign pointer to GD's "gdImage". It is expected as the first argument of most of procedures whose names starting with prefix `gd-image-'.


class: <gd-font>

Another fundamental class. Its instance has a foreign pointer to GD's "gdFont". You can get its instance by any of "gd-font-get-*".


variable: gdMaxColors

variable: gdAlphaMax

variable: gdAlphaOpaque

variable: gdAlphaTransparent

variable: gdRedMax

variable: gdGreenMax

variable: gdBlueMax

variable: gdFTEX_LINESPACE

variable: gdFTEX_CHARMAP

variable: gdFTEX_RESOLUTION

variable: gdFTEX_DISABLE_KERNING

variable: gdFTEX_XSHOW

variable: gdFTEX_FONTPATHNAME

variable: gdFTEX_FONTCONFIG

variable: gdFTEX_RETURNFONTPATHNAME

variable: gdFTEX_Unicode

variable: gdFTEX_Shift_JIS

variable: gdFTEX_Big5

variable: gdArc

variable: gdPie

variable: gdChord

variable: gdNoFill

variable: gdEdged

variable: GD2_CHUNKSIZE

variable: GD2_CHUNKSIZE_MIN

variable: GD2_CHUNKSIZE_MAX

variable: GD2_VERS

variable: GD2_FMT_RAW

variable: GD2_FMT_COMPRESSED

variable: GD_CMP_IMAGE

variable: GD_CMP_NUM_COLORS

variable: GD_CMP_COLOR

variable: GD_CMP_SIZE_X

variable: GD_CMP_SIZE_Y

variable: GD_CMP_TRANSPARENT

variable: GD_CMP_BACKGROUND

variable: GD_CMP_INTERLACE

variable: GD_CMP_TRUECOLOR

variable: GD_RESOLUTION

Each of these is an integer corresponding to its C-alternative.


variable: GD2_ID

It has a string value same with its C-equivalent.


procedure: gd-true-color-get-alpha c

procedure: gd-true-color-get-red c

procedure: gd-true-color-get-green c

procedure: gd-true-color-get-blue c

Each of these is equivalent to gdTrueColorGetAlpha, gdTrueColorGetRed, gdTrueColorGetGreen, or gdTrueColorGetBlue respectively.


procedure: gd-alpha-blend dest src

This is equivalent to gdAlphaBlend.


procedure: gd-image-create sx sy

procedure: gd-image-create-palette sx sy

procedure: gd-image-create-true-color sx sy

Each of these is a constructor of <gd-image> which is equivalent to gdImageCreate, gdImageCreatePalette, or gdImageCreateTrueColor respectively. If failed these return #f.


procedure: gd-image-create-from-png path

procedure: gd-image-create-from-gif path

procedure: gd-image-create-from-jpeg path

procedure: gd-image-create-from-wbmp path

procedure: gd-image-create-from-xbm path

procedure: gd-image-create-from-gd path

procedure: gd-image-create-from-gd2 path

procedure: gd-image-create-from-gd2-part path

Like C's gdImageCreateFrom* family, one of these creates a <gd-image> object from a source file in its particular image format. Unlike its C's equivalents, it treats the string-value single argument as a path of source. The file handle has been closed before successful return. In case of failure #f is returned.


procedure: gd-image-create-from-xpm path

The gdImageCreateFromXpm equivalent, which returns a <gd-image> object in case of success, otherwise #f.


procedure: gd-image-destroy im

Call gdImageDestroy() explicitly. Different from the C version it is idempotent, meaning that it can be repeated safely.

(Because of gc, it is little necessary to use this procedure.)


procedure: gd-image-set-pixel im x y color

procedure: gd-image-get-pixel im x y

procedure: gd-image-get-true-color-pixel im x y

Each of these is equivalent to gdImageSetPixel, gdImageGetPixel, or gdImageGetTrueColorPixel respectively.


procedure: gd-image-line im x1 y1 x2 y2 color

The gdImageLine alternative.


procedure: gd-image-rectangle im x1 y1 x2 y2 color

procedure: gd-image-filled-rectangle im x1 y1 x2 y2 color

Each of these is equivalent to gdImageRectangle or gdImageFilledRectangle respectively.


procedure: gd-image-set-clip im x1 y1 x2 y2

procedure: gd-image-get-clip im

As well as gdImageSetClip the former one clips a rectangle from the image for subsequent drawing. The latter returns the current clip with four integer-values.


procedure: gd-image-bounds-safe im x y

Given the coordinates of a point, return either 1 (if it is in the current clip) or 0 (otherwise). You should use it in order to check whether the coordinates is suitable or not for arguments of another procedure, e.g. gd-image-fill.


procedure: gd-image-char im f x y c color

procedure: gd-image-char-up im f x y c color

Put a single byte character on the given image with the font provided by a gd-font-get-*. If you would like to print a string containing multibyte characters, try procedure "gd-image-string-ft" or method "string!".


procedure: gd-image-string im f x y s color

procedure: gd-image-string-up im f x y s color

Put a string consising of single byte characters, with the font provided by a gd-font-get-*. If you would like to print a string containing multibyte characters, try gd-image-string-ft.


procedure: gd-image-string-ft im fg fontlist ptsize angle x y str

Print a string with a FreeType font specified by the path `fontlist'. Unlike the original version, it return *four* pairs of integers which represent the coordinates of the points surrounding the bounding rectangle, and coming lower-left, lower-right, upper-right, and upper-left in that order.

It is also possible to obtain these values efficiently, i.e. without printing `str', by giving #f to `im'.

If your gosh is configured with option "--enable-multibyte=utf-8", then congratulations! and multibyte characters will be available in `str' (with an appropriate font, of course). Otherwise you had better use method "string!".


procedure: gd-image-polygon im points pointsTotal color

procedure: gd-image-filled-polygon im points pointsTotal color

procedure: gd-image-open-polygon im points pointsTotal color

The second argument of these procedure, which expresses a sequence of points, must satisfy the following conditions:

- of type proper <list>, and

- its elements are of type <pair> and consist of integers which correspond to the coordinates of a point.

Furthermore the third one is expected to be a non-negative integer.


procedure: gd-image-color-allocate im r g b

procedure: gd-image-color-allocate-alpha im r g b a

procedure: gd-image-color-closest im r g b

procedure: gd-image-color-closest-alpha im r g b a

procedure: gd-image-color-closest-hwb im r g b

procedure: gd-image-color-exact im r g b

procedure: gd-image-color-exact-alpha im r g b a

procedure: gd-image-color-resolve im r g b

procedure: gd-image-color-resolve-alpha im r g b a

Each of these corresponds to gdImageColorAllocate, gdImageColorAllocateAlpha, gdImageColorClosest, gdImageColorClosestAlpha, gdImageColorClosestHWB, gdImageColorExact, gdImageColorExactAlpha, gdImageColorResolve, or gdImageColorResolveAlpha respectively.


procedure: gd-true-color r g b

procedure: gd-true-color-alpha r g b a

Same as gdTrueColor or gdTrueColorAlpha resp. for each.


procedure: gd-image-color-deallocate im color

Similar to gdImageColorDeallocate it reduces a color in the palette.


procedure: gd-image-create-palette-from-true-color im ditherFlag colorsWanted

procedure: gd-image-true-color-to-palette im ditherFlag colorsWanted

Both convert a true color image into the palette one while the latter destructively returns into the result argument `im'. If the former fails it returns #f


procedure: gd-image-color-transparent im color

The gdImageColorTransparent equivalent.


procedure: gd-image-palette-copy dst src

The gdImagePaletteCopy alternative.


procedure: gd-image-filled-arc im cx cy w h s e color style

procedure: gd-image-arc im cx cy w h s e color

Like gdImageFilledArc or gdImageArc respectively.


procedure: gd-image-filled-ellipse im cx cy w h color

The gdImageFilledEllipse equivalent.


procedure: gd-image-fill-to-border im x y border color

procedure: gd-image-fill im x y color

Each of these is equivalent to gdImageFillToBorder or gdImageFill respectively.


procedure: gd-image-copy dst src dstX dstY srcX srcY w h

procedure: gd-image-copy-merge dst src dstX dstY srcX srcY w h pct

procedure: gd-image-copy-merge-gray dst src dstX dstY srcX srcY w h pct

procedure: gd-image-copy-resized dst src dstX dstY srcX srcY dstW dstH srcW srdH

procedure: gd-image-copy-resampled dst src dstX dstY srcX srcY dstW dstH srcW srdH

procedure: gd-image-copy-rotated dst src dstX dstY srcX srcY srcWidth srdHeight angle

Note that some of these will preserve the palette of the given destination image as well as their C-equivalents.


procedure: gd-image-set-brush im brush

procedure: gd-image-set-tile im tile

procedure: gd-image-set-anti-aliased im c

procedure: gd-image-set-anti-aliased-dont-blend im c dont_blend

procedure: gd-image-set-thickness im thickness

procedure: gd-image-interlace im interlaceArg

procedure: gd-image-alpha-blending im blending

procedure: gd-image-save-alpha im saveFlag

The following functions are called respectively: gdImageSetBrush, gdImageSetTile, gdImageSetAntiAliased, gdImageSetAntiAliasedDontBlend, gdImageSetThickness, gdImageInterlace, gdImageAlphaBlending, and gdImageSaveAlpha.


procedure: gd-image-set-style im style styleLength

Given style as a list, call gdImageSetStyle.


procedure: gd-image-true-color im

It returns 0 for a palette image, otherwise non-0.


procedure: gd-image-sx im

procedure: gd-image-sy im

Each returns the sx(`width') or sy(`height') of the image respectively.


procedure: gd-image-colors-total im

Given a palette image it returns the number of currently allocated colors in the palette.


procedure: gd-image-red im c

procedure: gd-image-green im c

procedure: gd-image-blue im c

procedure: gd-image-alpha im c

Each of these corresponds to gdImageRed, gdImageGreen, gdImageBlue, or gdImageAlpha respectively.


procedure: gd-image-get-transparent im

procedure: gd-image-get-interlaced im

Each of these is equivalent to gdImageGetTransparent or gdImageGetInterlaced respectively.


procedure: gd-image-palette-pixel im x y

procedure: gd-image-true-color-pixel im x y

These inherits the bounds-unsafe nature from their C-alternatives.


procedure: gd-image-compare im1 im2

Return 0 If two images are same wrt displayed components, otherwise non-0.


procedure: gd-image-square-to-circle im radius

procedure: gd-image-sharpen im pct

Like gdImageSquareToCircle or gdImageSharpen respectively. The former returns #f in case of failure.


procedure: gd-font-get-giant

procedure: gd-font-get-large

procedure: gd-font-get-medium-bold

procedure: gd-font-get-small

procedure: gd-font-get-tiny

One of these procedures give you the font of size Giant, Large, MediumBold, Small, or Tiny respectively, which is for gd-image-char, gd-image-string etc. When the specified size is unavailable it return #f.


Simple API

(Experimental. See graphics/gd.scm and example/*.scm if interested.)

constant: *gd-version*

The version of GD library. Detected at the compile time of the package.


constant: *gd-features*

A list of symbols which mean available features of GD.

Possible symbols in the list: fontconfig freetype gif jpeg png xpm.

You can also use feature identifiers of form 'gauche.ext.graphics.gd.*' with cond-expand.

Note that they are available after loading the module.


parameter: current-gd-image-format

It is expected to keep a symbol which decides the image format taken with "read-gd-image" and/or "write" unless specified.


procedure: with-gd-image-format fmt thunk

Call `thunk' with the parameterized "current-gd-image-format" of value `fmt'.


method: read-gd-image (port <port>) &optional (fmt <symbol>) &keyword x y w h

Read a image with or without format `fmt' (such as "gif", "jpe", "jpeg", "jpg", "png", "wbmp", "gd", and "gd2"). See also "current-gd-image-format", or #f if an error occurs.

The keywords `x', `y', `w' and `h' are only for the GD2 format and corresponding to the 2nd, 3rd, 4th and 5th argument of "gdImageCreateFromGd2PartCtx" respectively.


method: write-as (im <gd-image>) (fmt <symbol>) port &keyword quality foreground

Put a image `im' with format `fmt' (such as "gif", "jpe", "jpeg", "jpg", "png", and "wbmp").

If the JPEG format specified, you can suggest the `quality' of the resulting image. The keyword is just ignored otherwise.

If the WBMP format specified, you can set the color index of pixels which are considered as `foreground'. The keyword is just ignored otherwise.


method: display (im <gd-image>) &optional port

method: write (im <gd-image>) &optional port

They are the same abbreviations of "write-as". See also "current-gd-image-format".


method: save-as (im <gd-image>) (path <string>)

method: save-as (im <gd-image>) (path <string>) (fmt <symbol>) &keyword quality foreground chunk-size compress

It provides another way to output a image. It tries to create a file of path `path' even if exists and return 0 in case of success. In the former case it choices the output image format by the extension (such as "gif", "jpe", "jpeg", "jpg", "png", "wbmp", "gd", and "gd2") of the path. Explicit `fmt' is used in the latter.

Available formats (if supported): GIF, JPEG, PNG, WBMP, GD, AND GD2.

If the GD2 format specified, you can set the options of the resulting image by the keywords `chunk-size' and `compress'. If a true value following `compress' (default), then the image will be compressed with the given `chunk-size' (or, a default one without `chunk-size'). Otherwise it will be uncompressed.

See "write-as" on the keyword `quality' for JPEG and `foreground' for WBMP.


method: char! (im <gd-image>) (f <gd-font>) (x <integer>) (y <integer>) (c <integer>) (color <integer>) &keyword direction

Put a character on the given `im'. If symbol 'up follows keyword `direction', "gd-image-char-up" is called instead of "gd-image-char".


method: string! (im <gd-image>) (f <gd-font>) (x <integer>) (y <integer>) (str <string>) (color <integer>) &keyword direction

method: string! (im <gd-image>) (fg <integer>) (font <string>) (pt <real>) (angle <real>) (x <integer>) (y <integer>) (str <string>)

method: string! (im <gd-image>) (x <integer>) (y <integer>) (str <string>) &keyword font fg pt angle

The first variant calls either "gd-image-string" or "gd-image-string-up" according to the symbol following keyword `direction'.

The usage of the second one is consistent with "gd-image-string-ft".

The third, an abbreviation of the second, treats default values of parameters if not specified with keywords. See also "current-ft-*" and "with-ft-font/fg/pt/angle".


parameter: current-ft-font

parameter: current-ft-fg

parameter: current-ft-pt

parameter: current-ft-angle

Sometimes it is useful to fix parameters in question to print strings subsequently on an image. These are reserved for such a case and its values are referred in a call of "string!" without optional arguments or keywords.


procedure: with-ft-font/fg/pt/angle font fg pt angle thunk

Call `thunk' with parameterized current-ft-font, current-ft-fg, current-ft-pt, and current-ft-angle. Its return value is `thunk''s one.


method: gif-anim-begin (im <gd-image>) (oport <port>) (GlobalCM <integer>) (loops <integer>)

method: gif-anim-add (im <gd-image>) (oport <port>) (localCM <integer>) (LeftOfs <integer>) (TopOfs <integer>) (Delay <integer>) (Disposal <integer>) &optional (previm <gd-image>)

method: gif-anim-end (oport <port>)

Create and output a GIF Animation. In case of calling gif-anim-add without the last argument `previm', GD does not optimize the resulting frames.

Rather than a pair of gif-anim-begin and gif-anim-end, gif-anim-with is often preferable.


procedure: gif-anim-with im oport thunk &keyword global-cm loop

Call `thunk' with gif-anim-began `im' and `port'. Before returning the procedure successfully, gif-anim-end is called expectedly.


method: pixel-for-each (im <gd-image>) proc

method: pixel-fold (im <gd-image>) proc knil

pixel-for-each calls 'proc' once for each pixel of image 'im' with arguments: x-coordinate, y-coordinate, and its pixel value obtained by 'gd-image-get-pixel'. Its return value is unspecified.

This allows you to write a filter as:

(define-method invert (im <gd-image>)
  (pixel-for-each im
                  (lambda (x y pixel)
                    (gd-image-set-pixel im x y pixel
                                        (gd-true-color (- 255 (gd-image-red im pixel))
                                                       (- 255 (gd-image-green im pixel))
                                                       (- 255 (gd-image-blue im pixel)))))))

pixel-fold calls 'proc' once for each pixel of image 'im' with 4 argumens: x-coordinate, y-coordinate, its pixel value, and the temporary seed, and returns the resulting reduction.


© 2006-2011 Takeshi Abe