Gauche-gd リファレンスマニュアル

For version 0.3.1

last update: Thu Mar 24 2011

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

C Layer API

class: <gd-image>

基本となるイメージのクラスです。実際には GD の "gdImage" への foreign pointer です。"gd-image-" (C では "gdImage")で始まるほとんどの手続きで第1引数として用いられます。


class: <gd-font>

基本となるフォントのクラスです。実際には GD の "gdFont" への foreign pointer です。手続き "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

それぞれ C の同名の定数と同じ数値を値に持ちます。


variable: GD2_ID

C の同名の定数と同じ文字列を値に持ちます。


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

それぞれ gdTrueColorGetAlpha, gdTrueColorGetRed, gdTrueColorGetGreen, gdTrueColorGetBlue に対応します。


procedure: gd-alpha-blend dest src

gdAlphaBlend に対応します。


procedure: gd-image-create sx sy

procedure: gd-image-create-palette sx sy

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

それぞれ gdImageCreate, gdImageCreatePalette, gdImageCreateTrueColor に対応し、<gd-image> オブジェクトを返します。失敗した場合は #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

C の gdImageCreateFrom* 関数と同様に、これらの手続きはそれぞれ特定のイメージフォーマットに応じてファイルから <gd-image> オブジェクトを作成します。ただ C の同等の関数と異なり、引数にソースファイルのパスを文字列で指定します。手続きに成功して戻った場合にはソースファイルのハンドルは閉じられています。失敗した場合には #f を返します。


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

C の gdImageCreateFromXpm に対応する手続きです。成功した場合には <gd-image> オブジェクトを、失敗した場合には #f を返します。


procedure: gd-image-destroy im

<gd-image> オブジェクトの指している "gdImage" リソースに対して明示的に gdImageDestroy を呼びます。繰り返し呼ばれても安全です。

(メモリに関する特別な制限のない限り、こういったリソースの解放は gc に任せておいて構いません。)


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

それぞれ gdImageSetPixel, gdImageGetPixel, gdImageGetTrueColorPixel に対応します。


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

関数 gdImageLine に対応する手続きです。


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

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

それぞれ gdImageRectangle, gdImageFilledRectangle に対応する手続きです。


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

procedure: gd-image-get-clip im

gdImageSetClip と同様に gd-image-set-clip は以後の描画に適用されるクリップ領域を設定します。gd-image-get-clip は現在のクリップ領域の座標を表す4つの数値を返します。


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

クリップ領域内の座標があたえられた場合は1を、さもなくば0を返します。gd-image-fill などの手続きの引数に適した座標かどうかを確認するためにこの関数を利用するべきです。


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

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

イメージへ1バイト文字を出力します。第2引数のフォントは手続き gd-font-get-* から取得してください。マルチバイト文字を含む文字列を出力する場合には手続き "gd-image-string-ft" またはメソッド "string!" を使ってください。


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

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

イメージへ1バイト文字からなる文字列を出力します。第2引数のフォントは手続き gd-font-get-* から取得してください。マルチバイト文字を含む文字列を出力する場合には手続き "gd-image-string-ft" またはメソッド "string!" を使ってください。


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

`fontlist' でパスを指定することで FreeType フォントを用いて文字列を書き出します。オリジナルの C の関数と異なり、この手続きは*4つ*のペアを返し、それぞれが出力先の矩形を囲む座標(順に左下、右下、右上、左上)を表します。

`im' に #f を渡すことで描画せずにこの矩形の座標を効率的に求めることができます。

gosh が "--enable-multibyte=utf-8" というオプション付きでビルドされていれば `str' でマルチバイト文字が利用できます。そうでない場合はメソッド "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

これらの手続きはそれぞれ gdImagePolygon, gdImageFilledPolygon, gdImageOpenPolygon に対応します。ただし、いずれも座標列を表す第2引数として循環の無いリストを指定します。このリストの各要素は座標を表すペアでなければなりません。さらに第3引数は非負整数であることが求められます。


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

それぞれ C の関数 gdImageColorAllocate, gdImageColorAllocateAlpha, gdImageColorClosest, gdImageColorClosestAlpha, gdImageColorClosestHWB, gdImageColorExact, gdImageColorExactAlpha, gdImageColorResolve, gdImageColorResolveAlpha に対応します。


procedure: gd-true-color r g b

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

それぞれ C の関数 gdTrueColor, gdTrueColorAlpha に対応します。


procedure: gd-image-color-deallocate im color

gdImageColorDeallocate と同様にパレットの色情報を破棄し再利用できるようにします。


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

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

いずれも true color イメージをパレットイメージに変換します。ただし後者は与えられたイメージを破壊的に変更しその引数に結果を返します。また前者が失敗した場合 #f が返ります。


procedure: gd-image-color-transparent im color

関数 gdImageColorTransparent に対応します。


procedure: gd-image-palette-copy dst src

関数 gdImagePaletteCopy に対応します。


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

それぞれ gdImageFilledArc, gdImageArc に対応します。


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

関数 gdImageFilledEllipse に対応します。


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

procedure: gd-image-fill im x y color

それぞれ gdImageFillToBorder, gdImageFill に対応します。


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

これらの手続きの中には対応する gdImageCopy* 関数と同じように与えられたコピー先のパレットを変更しないものもあることに注意してください。


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

それぞれ gdImageSetBrush, gdImageSetTile, gdImageSetAntiAliased, gdImageSetAntiAliasedDontBlend, gdImageSetThickness, gdImageInterlace, gdImageAlphaBlending, gdImageSaveAlpha に対応します。


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

style をリストとして与えることで gdImageSetStyle を呼びます。


procedure: gd-image-true-color im

パレットイメージが与えられた場合は0を、さもなくば0以外の数値を返します。


procedure: gd-image-sx im

procedure: gd-image-sy im

それぞれ与えられたイメージの横もしくは縦の幅を返します。


procedure: gd-image-colors-total im

パレットイメージが与えられた場合、パレットの色数を返します。


procedure: gd-image-red im c

procedure: gd-image-green im c

procedure: gd-image-blue im c

procedure: gd-image-alpha im c

それぞれ gdImageRed, gdImageGreen, gdImageBlue, gdImageAlpha に対応します。


procedure: gd-image-get-transparent im

procedure: gd-image-get-interlaced im

それぞれ gdImageGetTransparent, gdImageGetInterlaced に対応します。


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

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

これらの手続きはマクロ gdImagePalettePixel や gdImageTrueColorPixel を直接呼び出すため、引数が適切かどうか事前に確認する必要があるでしょう。


procedure: gd-image-compare im1 im2

与えられた2つのイメージが描画される構成要素に関して等しければ0を、さもなくば0以外の数値を返します。


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

procedure: gd-image-sharpen im pct

それぞれ gdImageSquareToCircle, gdImageSharpen に対応します。前者は失敗した場合 #f を返します。


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

これらの手続きはそれぞれサイズが Giant, Large, MediumBold, Small, Tiny のフォントを返します。このフォントは gd-image-char や gd-image-string 等の引数に利用されます。フォントが得られない場合は #f を返します。


Simple API

(まだ試験的なものです。興味のある方は graphics/gd.scm や example/*.scm を見てください。)

constant: *gd-version*

GD のバージョン。Gauche-gd のコンパイル時に取得したものです。


constant: *gd-features*

有効な GD の機能を表すシンボルのリスト。

このリストに含まれる可能性のあるシンボルは以下の通り: fontconfig freetype gif jpeg png xpm。

また 'gauche.ext.graphics.gd.*' という形の feature indentifiers を cond-expand とともに使うこともできます。

これらの identifiers はモジュールのロード後に利用できます。


parameter: current-gd-image-format

GD のイメージは本来特定のフォーマットに依存しない形に抽象化されていますが、入出力を行う際に特定のフォーマットが前提になっていることがよくあります。"read-gd-image" や "write" は このパラメータの値を参照するので、そういった場合に利用できます。


procedure: with-gd-image-format fmt thunk

上記の "current-gd-image-format" の値を一時的に `fmt' にして `thunk' を呼びます。戻ると "current-gd-image-format" の値は復元されます。`thunk' の戻り値がこの手続きの戻り値です。


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

ポート `port' からイメージを入力します。エラーの場合は #f を返します。フォーマット `fmt' として取り得る値は "gif", "jpe", "jpeg", "jpg", "png", "wbmp", "gd", 及び "gd2" です。"current-gd-image-format" も参照してください。

キーワード `x'、`y'、`w' 及び `h' は GD2 フォーマットに対してのみ適用され、それぞれ "gdImageCreateFromGd2PartCtx" の 2番目、3番目、4番目及び5番目の引数に対応します。


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

ポートへイメージ `im' を出力します。フォーマット `fmt' に取り得る値は "gif", "jpe", "jpeg", "jpg", "png", 及び "wbmp" です。

JPEG フォーマットが指定された場合には、キーワード `quality' に与えられる値によって出力の質(と、結果的にサイズ)を調節できます。このキーワードが与えられない場合には GD によってデフォルトの値が利用されます。それ以外のフォーマットについては、単に無視されます。

WBMP フォーマットが指定された場合には、キーワード `foreground' によってビットがセットされるカラーインデックスを与えることができます。このインデックスを持たないピクセルは"背景"として扱われます。このキーワードが与えられない場合には GD はデフォルトの振る舞いをします。


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

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

"write-as" の省略形で、いずれも同じように振舞います。"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

イメージを出力するメソッドの1つです。`path' として与えられたファイルを(既存であっても)新しく作成します。成功した場合は0を返します。前者の形で呼ばれた場合、出力イメージフォーマットは `path' の拡張子によって選択されます。判別される拡張子は "gif", "jpg", "jpeg", "jpe", "png", "wbmp", "gd", "gd2" です。後者の形で明示的にフォーマット `fmt' を与えられます。

(サポートしていれば)利用できるフォーマットは GIF, JPEG, PNG, WBMP, GD, GD2 です。

GD2 フォーマットが指定された場合、キーワード `chunk-size' 及び `compress' によってオプションを指定できます。`compress' に対して真の値が与えられたとき(デフォルト)には、書き出されるイメージは `chunk-size' の値を使って圧縮されます。`chunk-size' が与えられない場合、GD はデフォルトのサイズを選択します。`compress' が偽なら圧縮されません。

JPEG フォーマットのためのキーワード `quality' や WBMP フォーマットのためのキーワード `foreground' については、"write-as" を参照してください。


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

イメージへ文字を書き出します。キーワード `direction' に続いてシンボル 'up が指定された場合、"gd-image-char" の代わりに "gd-image-char-up" が呼ばれます。


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

最初の形はキーワード `direction' とともに与えられるシンボルに従って "gd-image-string" または "gd-image-string-up" を呼び出します。

2番目の形は "gd-image-string-ft" の呼び出しと対応します。

最後の形は2番目の略記で、キーワードとともにパラメータが指定されなければデフォルトの値を用います。"current-ft-*" や "with-ft-font/fg/pt/angle" も参照してください。


parameter: current-ft-font

parameter: current-ft-fg

parameter: current-ft-pt

parameter: current-ft-angle

イメージ上へ連続して文字列を出力する際、関係するパラメータを固定すると便利な場合があります。こういった場合のためにこれらのパラメータが用意されており、オプショナルな引数やキーワードで指定されずに "string!" が呼ばれた時に参照されます。


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

current-ft-font, current-ft-fg, current-ft-pt, current-ft-angle を与えられた値にして `thunk' を呼びます。戻ると `thunk' からの戻り値を返し、current-ft-* の値は復元されます。


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>)

これらのメソッドによって GIF アニメーションを出力します。gif-anim-add の最後の引数を省略した場合、GD は自動的な最適化を行いません。

gif-anim-end と gif-anim-end を対にして使うより、手続き gif-anim-with を利用することを勧めます。


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

この手続きは、まず `im' と `port' とキーワードに与えられた値を引数にして gif-anim-begin を呼び、その上で `thunk' を呼びます。無事に手続きから戻る前に gif-anim-end を呼びます。


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

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

メソッド pixel-for-each は各ピクセルごとに x 座標、y 座標、および gd-image-get-pixel の値の3つの引数で 'proc' を呼びます。戻り値は不定です。

このメソッドによって次のようなフィルターを書くことができます:

(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 は初期値 knil をもとに、各ピクセルごとに x、y、ピクセル値、およびその時点での畳み込みされた値の4つの引数で 'proc' を呼びます。戻り値は畳み込まれた値です。


© 2006-2011 Takeshi Abe