gd ライブラリの index.htm (version 1.3) のあてにならない参考のための抄訳です

リファレンスの未訳の部分は原文のままとしています。
・・・訳文は信頼しないでください。ええと、英語と画像は不得手なんだってばぁ・・・
日本語訳の、誤りや疑問点については、 gama <gama@mvg.biglobe.ne.jp> までお知らせください。
・・・ってったって、誤りや疑問点だらけだよなぁ(^^;;;

New Version! gd 1.8.3 のあてにならない参考のための抄訳
gd 1.2 のインストール方法と README のあてにならない抄訳


GD ライブラリについての日本語による情報
PostgreSQL での GD グラフィックライブラリの解説 日本語表示のパッチがあります。

STEP 7 へ戻る| ホーム へ

gd 1.3

GIF 高速作成用グラフィックスライブラリ

この ドキュメントの最新版(英語原文)は、ここ にあります。

目次

Boutell.Com, Inc. のホームページ

クレジットとライセンスについて

 以下の著作権表示は、gd ライブラリの著作権者についての問題を可能なかぎり回避するために、 表示されるべき著作権者をすべて網羅しています。 さらに、特許が問題となり、取り除かれてしまいましたが、 gd が、最近まで使っていた LZW による GIF 圧縮のコードに対して David Rowley に感謝します。 この著作権表示について問題点を見つけた場合は、 Thomas Boutellまで、 お知らせくださいますようにお願いします。 よろこんで訂正します。

著作権表示は以下のとおり
Portions copyright 1994, 1995, 1996, 1997, 1998, by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health.

Portions copyright 1996, 1997, 1998, by Boutell.Com, Inc.

GIF decompression code copyright 1990, 1991, 1993, by David Koblas (koblas@netcom.com).

Non-LZW-based GIF compression code copyright 1998, by Hutchison Avenue Software Corporation (http://www.hasc.com/, info@hasc.com).

この表示を、ユーザーが見る事のできる、 サポーティングドキュメンテーションの中に記載する事により、 商業的アプリケーションも含めた、あらゆる gd の複製と再配布が認められます。

これは、あなたの作成した2次的著作物自体の権利に影響をおよぼすものではありませんし、 gd の著作権者についての正確なクレジットを表記する事が目的であって、 gd の生産的な利用を妨げる事ではありません。 疑問点があれば、お問いあわせください。 「2次的著作物」とは、このライブラリを利用したあらゆるプログラムを含みます。 ユーザーが見る事のできるサポーティングドキュメンテーションに クレジットが記載されていなければなりません。

すべての複製と、 そのサポーティングドキュメンテーションに、著作権についての表記と、 この使用条件についての表記が、なされていることを条件に、 このソフトウェアとドキュメンテーションの、 あらゆる使用、複製、改変、再配布が、無償で認められます。 このソフトウェアは、 "あるがまま(as is)" であり、 明示、暗黙を問わず、一切の保証がなされません。

以上

gd とは?

gd は、グラフィックスライブラリです。 あなたのプログラムによって、 直線、円弧、文字、いろんな色、他の画像からのカット&ペースト、 塗りつぶし、などによって、すばやく画像を作成し、 .GIF ファイルとして出力します。 .GIF をインラインイメージとして使うアプリケーションで、特に有用です。

gd は、お絵描き用のプログラムではありません。 お絵描き用のプログラムを探しているのなら見当ちがいですし、 あなたがプログラマーでないのならば見当ちがいです。

gd はすべての魅力的なグラフィック操作のために公開されているものではありません。 gd は台所の流し台のグラフィックパッケージ (訳注: a kitchen-sink graphics package  うーむ、慣用句なのかな? どういう意味なんでしょ?) になる必要はないし、そのつもりはありません。 version 1.3 では、8bit の 2次元のパッケージとして、 一般的に必要とされる機能を具体化しています。 スケーラブルフォント、自然色、JPEG と PNG のサポートは、version 2.0 として計画されています。 Version 1.3 は、長い間続いていた bug の修正と、 LZW ではない GIF 圧縮法を提供するために公開されました。

他のプログラミング言語をつかいたいときは?

Perl

gd は Perl からも使う事ができます。 Lincoln Stein の好意による GD.pm ライブラリで、 Perl 5.x のクラスのセットとして gd が使われています。 GD.pm は、gd 1.1.1 に基づいていますが、gd 1.2 とも互換性があります。

その他のプログラミング言語

gd を操作する簡易なインタープリタが、現在のところ、少なくとも3つ存在しています。

これらのパッケージは、gd 1.2 に基づいていますが、 わずかな修正によって gd 1.3 とも互換がとれると思われます。

1.3 の変更点

Version 1.3 は、以下のような点が変更されています。
Non-LZW-based GIF 圧縮法
Version 1.3 は LZW 圧縮法に代えて、 単純な Run Length Encoding による GIF 圧縮法を内包しています。 この圧縮法は、従来の LZW 圧縮法のデコーダとも互換性があります。 (あなたのブラウザは、GIF 画像を見ることができるでしょ?) LZW 圧縮法は Unisys 社の特許です。 長い間、gd の新しいバージョンが公開されなかったのは、それが原因でした。 Hutchison Avenue Software Corporation による新コードの提供に感謝します。 この新コードは、 写真のイメージの圧縮には適していませんが、より大きな GIF 画像が取り扱えます。 これは、合法的な行為であり、いかなる技術上の疑問点もありません。 GIF の出力のサイズについては、なげかないでくださいね。
8-bit フォントと 8-bit フォントサポート
欧文のサポートを実現しました。 Honza Pazdziora と Jan Pazdziora に感謝! 等幅の X11 フォントを gd のフォントへ変換する Perl スクリプト bdftogd もご覧ください、
16-bit フォントサポート (フォントは含まれていません)
フォントは含まれていませんが、 gdImageString16 と gdImageStringUp16 によって、 256 種以上の文字を扱えるようになりました。
実例/ユーティリティーの "webgif" が改良されました。
"webgif" ユーティリティーが軽く、より有用なアプリケーションとなりました。 Brian Dowling に感謝!
GIF 出力の color resolution field が修正されました。
Thanks to Bruno Aureli.
多角形の塗りつぶしのバグフィックス
(訳注:略)
Row-major, not column-major
(訳注:手に余るので(^^;;; 略)

gd ライブラリをつかうために必要な環境

gd を使うためには、ANSI C コンパイラが必要です。 Windows 95/NT のすべてのポピュラーな C コンパイラーは ANSI C に準拠しています。 ANSI 完全準拠の C コンパイラであれば、問題ないとおもわれます。 SunOS 4.1.3についてくる cc コンパイラは ANSI C コンパイラではありません。 gcc をまだ入手していない Unix ユーザーは、入手してください。 gcc は ANSI 準拠の無償の C コンパイラとして、事実上の標準になっています。 なぜ、gcc がないのかをインターネットサービスプロバイダへ尋ねてください。

結果を確認するために、GIF ビューワーも必要です。(訳注:中略)

gd の入手方法

By HTTP

By FTP

gd のインストール

gd をインストールするには、最初にダウンロードしてきたアーカイブを展開する必要があります。 targunzip (Unix) または ZIP (Windows) を知らない場合には、そのシステムでの経験を積んだユーザーに相談してください。 残念ながら、そうした基本的な技術についての質問には、当方では、お答えする事ができません。
(訳注:"gunzip gd1.3.tar.gz" してから "tar -xf gd1.3.tar")

アーカイブを展開すると "gd1.3" というディレクトリが作成されます。

For Unix

cd で gd1.3 ディレクトリに移り、Makefile を見てみる事、 おそらく、使用するオペレーティングシステムと、使い方によって、 多少の変更をする必要があると思われます。

For Windows, Mac, その他いろいろ

(訳注:中略)

さて、つぎに、デモンストレーションプログラムを生成します。 コマンドラインからならば "make gddemo" とタイプするだけです (訳注:中略) うまくいけば、問題なく "gddemo" がコンパイル、リンクされます。 使用するシステムによって、Makefile を修正する必要があります。 使用しているシステムでのコンパイル、リンクなどの基本的なテクニックについては、 自分で解決する事。

これで、gd のデモンストレーションプログラムの生成が終了しました。 動作を確認するため "gddemo" とタイプします。 (訳注:Unix では "./gddemo" の方が無難です。)

gddemo は、指定しない場合には、demoout.gif を作成します。 (注記、demoin.gif というファイルが、 デモンストレーション用として同梱で供給されています。)

GIF ビューワで demoout.gif を表示して見てください。 128x128 ピクセルのスペースシャトルのイメージに、 いろんなグラフィカルな要素が上書きされていまよね。

(もしも demoin.gif ファイルがなくなっていれば、なにか他のものが表れています。)

demoin.gif をみてください、 スペースシャトルの元のイメージが、 調整され、出力イメージへ複写されています。

gd 基礎: gd の使用方法

gd は動的に GIF イメージを作り出します。 gd をプログラムで使うためには、gd.h を include し、 Unix上では "make libgd.a" によって作成された libgd.a ライブラリをリンクします。 他のオペレーティングシステムでは gd.c を project に追加してください。

提供されているフォントを使う場合には、 gdfontt.h, gdfonts.h, gdfontmb.h, gdfontl.h の4つ、 または gdfontg.h を含めて5つのファイルをインクルードします。 あるいは、gdfontg.h だけをインクルードします。 提供されている Makefile やライブラリによる方法ではなく、 ソースを直接、独自のプロジェクトへ組み込む事もできます。 (16-bit メモリーモデルの DOS や Windows には、大きすぎると思われます。)

短いプログラム例 (より高度な例は、配布に含まれている gddemo.c を参照してださい。 gddemo.c は、より高度な機能のデモンストレーションです!)

/* gd ライブラリ機能を使う指定 */
#include "gd.h"

/* standard I/O を使う指定。作成した GIF をファイルに出力するので。 */
#include <stdio.h>

int main() {
    /* イメージを宣言 */
    gdImagePtr im;
    /* 出力ファイルの宣言 */
    FILE *out;
    /* カラーインデックスの宣言 */
    int black;
    int white;

    /* イメージを確保する: 64 x 64 ピクセル */
    im = gdImageCreate(64, 64);

    /* カラー black の宣言(red, green, blue すべて最小値)。
        これによって、新しいイメージの背景色となる最初の色が決まる。
         */
    black = gdImageColorAllocate(im, 0, 0, 0);  

    /* カラー white の宣言(red, green, blue すべて最大値) */
    white = gdImageColorAllocate(im, 255, 255, 255);    
    
    /* カラー white をつかって、左上から右下へ線を描く  */
    gdImageLine(im, 0, 0, 63, 63, white);    

    /* ファイルを出力用に Open. "wb" は "write binary" を意味する。
        MSDOS 上では重要な意味を持つが、Unix 上では意味を持たない。 */
    out = fopen("test.gif", "wb");

    /* イメージをディスクファイルに出力する。 */
    gdImageGif(im, out);  

    /* ファイルを Close */
    fclose(out);

    /* メモリー上のイメージを破棄 */
    gdImageDestroy(im);
}
実行時に、このプログラムは、1つのイメージを作成し、 2つのカラー割り当て (最初のカラーは背景色となる)、 1本の対角線を引く (0, 0 は左上の隅)、 GIF ファイルへイメージを書き出し、 イメージを破棄しています。

上の例のプログラムによって、 パッケージがどんな仕事をするのか、大体の感じをつかんでください。 gd は、以下のリファレンスで、 それぞれコードの断片を示し、列挙したように、 さまざまの付加的な機能を提供しています。 アルファベット順のインデックス も提供しています。

Webgif: より有用な gd の実例

Webgif はコマンドラインによって GIF を操作するシンプルなユーティリティープログラムです。 Unix または類似のコマンドラインシステムのために作成されましたが、 他の環境にも容易に移植する事が可能だと思います。 Webgif は、透過とインターレースを指定することによって、 GIF の疑問点に対して興味深い情報を出力してくれます。

webgif.c は同梱して配布されています。 Unix ユーザーは "make webgif" とタイプするだけでコンパイルする事ができます。 "webgif" と引数なしで起動すると有効なオプションを表示します。 (訳注:Unix では "./webgif" の方が無難です。)

関数とタイプのリファレンス

タイプ(Types)

gdImage(TYPE)
gd がイメージを格納するために使用する構造体。 gdImageCreate は、この type へのポインタを返す。 多くの関数がこの type へのポインタを最初のアーギュメントとして使用する。 メンバーとして sx (X 方向のサイズ), sy (y 方向のサイズ), colorsTotal(色数の合計), red (red カラー要素; 0 から 255 までの値の 256 の整数のならびである), green (green カラー要素、同様です)、 blue (blue カラー要素、同様です)、 透過(transparent)(透過するカラーのインデックス、設定されてない時は -1) が参照できるが、 直接参照せずに、提供されているマクロを使用する事。 また、メンバーを直接設定しないで、提供されている関数を使用する事。
typedef struct {
    unsigned char ** pixels;
    int sx;
    int sy;
    int colorsTotal;
    int red[gdMaxColors];
    int green[gdMaxColors];
    int blue[gdMaxColors]; 
    int open[gdMaxColors];
    int transparent;
} gdImage;
gdImagePtr (TYPE)
イメージ構造体へのポインタ。 gdImageCreate は、この type を返り値とする、多くの関数の最初のアーギュメントして使われる。
gdFont (TYPE)
フォントの構造体。フォントの特性を定義するために使用されている。 この構造体の適切な宣言の例としては gdfontl.c と gdfontl.h の2つのファイルを参照の事。 このような構造体と関係づけされたピクセルのならびを規定することによって、 あなたの固有のフォントデータをつかう事ができる。 構造体のメンバー w と h によって、 そのフォントの1文字の幅と高さを指定する。 あなたの固有のフォントを作らない場合は、 この構造体の他の部分に配慮する必要はない。
typedef struct {
    /* フォント内の文字数 */
    int nchars;
    /* ナンバーを振られる最初の文字... (普通は 32 = space) */
    int offset;
    /* 文字の幅と高さ */
    int w;
    int h;
    /* フォントデータ; 文字の並び、一列づつ順に並べる。
       プログラム内で記述してもよいが、
       データファイルからロードしてもよい。*/
    char *data;
} gdFont;
gdFontPtr (TYPE)
フォント構造体へのポインタ。テキスト出力関数で、 gdImagePtr アーギュメントに続く、 2番目のアーギュメントとして使われる。 この2つのポインタは、gdfonts.h と gdfontl.h で定義されている。
gdPoint (TYPE)
gdImagePolygongdImageFilledPolygon によって使われるイメージの同じ空間の位置を表わす。
typedef struct {
        int x, y;
} gdPoint, *gdPointPtr;
gdPointPtr (TYPE)
gdPoint 構造体へのポインタ; gdImagePolygongdImageFilledPolygon. へのアーギュメントとして使われる。

イメージの作成、破棄、ロードとセーブ

gdImageCreate(sx, sy) (FUNCTION)
gdImageCreate はイメージを作成するために使用される。 x,y を指定して gdImageCreate を実行する事によって要求されたイメージを作成する。 gdImageCreate は作成したイメージへのgdImagePtrを返す、 イメージを作成できなかった場合には、NULL が返る。 イメージはgdImageDestroy()によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
im = gdImageCreate(64, 64);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromGif(FILE *in) (FUNCTION)
gdImageCreateFromGif は GIF フォーマットのファイルからイメージをロードする。 すでにオープンされているイメージファイルのポインタを指定して gdImageCreateFromGif を実行する。 gdImageCreateFromGif は作成したイメージへのgdImagePtrを返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、GIF イメージではない。) gdImageCreateFromGif はファイルをクローズ しない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージはgdImageDestroy()によって破棄されなければならない。
gdImagePtr im;
... 関数の中で ...
FILE *in;
in = fopen("mygif.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromGd(FILE *in) (FUNCTION)
gdImageCreateFromGd は gd フォーマットのファイルからイメージをロードする。 すでにオープンされているgd ファイルフォーマット のイメージファイルのポインタを指定して gdImageCreateFromGd を実行する。 gdImageCreateFromGd は作成したイメージへのgdImagePtrを返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、gd ファイルフォーマットではない。) gdImageCreateFromGd はファイルをクローズ しない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージはgdImageDestroy()によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd", "rb");
im = gdImageCreateFromGd(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromXbm(FILE *in) (FUNCTION)
gdImageCreateFromXbm は X bigmap フォーマットのファイルからイメージをロードする。 すでにオープンされているイメージファイルのポインタを指定して gdImageCreateFromXbm を実行する。 gdImageCreateFromXbm は作成したイメージへのgdImagePtrを返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、X bigmap フォーマットのイメージではない。) gdImageCreateFromXbm はファイルをクローズ しない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージはgdImageDestroy()によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
FILE *in;
in = fopen("myxbm.xbm", "rb");
im = gdImageCreateFromXbm(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageDestroy(gdImagePtr im) (FUNCTION)
gdImageDestroy はイメージに割り当てられたメモリーを解放するために使用される。 gdImagePtrを新しいイメージを割りあてる前に、 gdImageDestroy を実行しておく事が重要である。
... 関数の中で ...
gdImagePtr im;
im = gdImageCreate(10, 10);
/* ... イメージを使う ... */
/* ここでメモリーを開放! */
gdImageDestroy(im);
void gdImageGif(gdImagePtr im, FILE *out) (FUNCTION)
gdImageGif は、指定されたイメージを指定されたファイルへ GIF フォーマットで出力する。 ファイルは、出力用としてオープンされていなければならない。 MSDOS 上では、open するモードとして、単に "w" ではなく "wb" を指定する事が重要である。 Unix 上で、同様な指定をしても悪影響はない。 gdImageGif は、ファイルをクローズ しない、 あなたのコードでクローズしなければならない。
... 関数の中で ...
gdImagePtr im;
int black, white;
FILE *out;
/* イメージの作成 */
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
white = gdImageColorAllocate(im, 255, 255, 255);
/* 描画色の割り当て */
black = gdImageColorAllocate(im, 0, 0, 0);
/* 長方形を描く */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* 出力ファイルをバイナリーモードでオープン */
out = fopen("rect.gif", "wb");
/* GIF を書く */
gdImageGif(im, out);
/* ファイルをクローズ */
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageGd(gdImagePtr im, FILE *out) (FUNCTION)
gdImageGd は、指定されたイメージを指定されたファイルへ gd イメージフォーマット で出力する。 ファイルは、出力用としてオープンされていなければならない。 MSDOS 上では、open するモードとして、単に "w" ではなく "wb" を指定する事が重要である。 Unix 上で、同様な指定をしても悪影響はない。 gdImageGd は、ファイルをクローズ しない、 あなたのコードでクローズしなければならない。

gd イメージフォーマットは、他のイメージを作る時に、 頻繁に必要とされるイメージを高速に読み書きすることを目的としている。 圧縮されていないフォーマットであり、 一般的に使用される事を意図していない。

... 関数の中で ...
gdImagePtr im;
int black, white;
FILE *out;
/* イメージの作成 */
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
white = gdImageColorAllocate(im, 255, 255, 255);
/* 描画色の割り当て */
black = gdImageColorAllocate(im, 0, 0, 0);
/* 長方形を描く */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* 出力ファイルをバイナリーモードでオープン */
out = fopen("rect.gd", "wb");
/* GIF を書く */
gdImageGd(im, out);
/* ファイルをクローズ */
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);

描画関数

void gdImageSetPixel(gdImagePtr im, int x, int y, int color) (FUNCTION)
gdImageSetPixel は指定されたカラーインデックスで1ピクセルを描く。 常に、この関数や、他の描画関数を使ってピクセルへアクセスし、 gdImage 構造体のピクセルを直接アクセスしない事。
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* まんなかあたりに1ピクセルを描く */
gdImageSetPixel(im, 50, 50, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)
gdImageLine は、2点間(x1,y1 と x2, y2)に直線を描くために使用される。 直線は、指定されたカラーインデックスによって描かれる。 カラーインデックスは、 gdImageColorAllocate gdStyled, gdBrushed gdStyledBrushed のいずれにかによって返された、 確保されているカラーでなくてはならない点に注意する。
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* 左上隅から右下隅まで直線を描く */
gdImageLine(im, 0, 0, 99, 99, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)
gdImageDashedLine は gd 1.0 との互換のために提供されている。 新しいプログラムでは、破線を書くのに、gdImageLine 関数と gdImageSetStyle 関数を使う事を推奨する。

gdImageDashedLine は、2点間(x1,y1 と x2, y2)に破線を描くために使用される。 破線は、指定されたカラーインデックスによって描かれる。 線の描かれない部分は、そのまま残されるので、背景のままとなる。

... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* 左上隅から右下隅まで破線を描く */
gdImageDashedLine(im, 0, 0, 99, 99);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color) (FUNCTION)
gdImagePolygon は各頂点(最低3点)とカラーインデックスを指定して多角形を描くのに使われる。 gdImageFilledPolygonも参照の事。
... 関数の中で ...
gdImagePtr im;
int black;
int white;
/* 多角形の頂点 */
gdPoint points[3];
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* 3角形を描く */
points[0].x = 50;
points[0].y = 0;
points[1].x = 99;
points[1].y = 99;
points[2].x = 0;
points[2].y = 99;
gdImagePolygon(im, points, 3, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)
gdImageRectangle は2つの頂点(左上と右下)とカラーインデックスを指定して長方形を描くのに使われる。
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* まんなかあたりに長方形を描く */
gdImageRectangle(im, 25, 25, 74, 74, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageFilledPolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color) (FUNCTION)
gdImageFilledPolygon は各頂点(最低3点)とカラーインデックスを指定して、 内部を塗りつぶした多角形を描くのに使われる。 gdImagePolygonも参照の事。
... 関数の中で ...
gdImagePtr im;
int black;
int white;
int red;
/* 多角形の頂点 */
gdPoint points[3];
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* カラー red の割り当て */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* 3角形を描く */
points[0].x = 50;
points[0].y = 0;
points[1].x = 99;
points[1].y = 99;
points[2].x = 0;
points[2].y = 99;
/* white で塗りつぶす */
gdImageFilledPolygon(im, points, 3, white);
/* 輪郭を red で描く(塗りつぶし後に輪郭を描く事に注意) */
gdImagePolygon(im, points, 3, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color) (FUNCTION)
gdImageFilledRectangle は2つの頂点(左上と右下) とカラーインデックスを指定して内部を塗りつぶした長方形を描くのに使われる。
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = int gdImageColorAllocate(im, 255, 255, 255);    
/* まんなかあたりに塗りつぶされた長方形を描く */
gdImageFilledRectangle(im, 25, 25, 74, 74, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color) (FUNCTION)
gdImageArc は、指定された中心と、ピクセル単位で指定された幅と高さで、 だ円を部分的に描くために使われる。 円弧は、 角度で指定された始点 s と 終点 e で指定される。 円は、 幅と高さを同じにし、 0度を始点とし、360度を終点とする事で描かれる。 終点 e は、 始点 s よりも大きくなくてはならない。 360度を超える値は、360 の剰余として処理される。
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 50);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* だ円を描く */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int color) (FUNCTION)
gdImageFillToBorder は、イメージの一部を color で指定された色で塗りつぶす、 指定された点から開始し border で指定された色で終了する。 始点の色と同じ色の部分を塗つぶす方法については、 gdImageFill を参照の事。

境界の色は、gdTiled のような特別な色 は使えない。 普通の色でなくてはならない。 塗つぶす色には、特別な色が指定できる。

注:gdImageFillToBorder は再帰的に処理される。 これは、最も容易な実現方法ではなく、 この実現方法は改良されることが望まれる。 しかし、 スタックが非常に深くなることが可能な場合には、改悪となるだろう。 これは MSDOS と MS Windows 環境での問題である。 (もちろん、適切なスタックがある Unix や NT 環境では、まったく問題ない。)

... 関数の中で ...
gdImagePtr im;
int black;
int white;
int red;
im = gdImageCreate(100, 50);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* カラー red の割り当て */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* だ円を描く */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* だ円の外側を塗りつぶす。 red で塗りつぶす、境界の色は、white (だ円) */
/* (訳注:だ円の内側を塗りつぶすということで、下の x,y が 50,25 だと分かりやすい気がするのですが?) */
gdImageFillToBorder(im, 50, 50, white, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageFill(gdImagePtr im, int x, int y, int color) (FUNCTION)
gdImageFill は、は、イメージの一部を color で指定された色で塗りつぶす、 指定された点から開始し、始点と同じ色の領域を塗りつぶす。 指定された色の境界の内部を塗つぶす方法については、 gdImageFillToBorder を参照の事。

The fill color can be gdTiled, resulting in a tile fill using another image as the tile. However, the tile image cannot be transparent. If the image you wish to fill with has a transparent color index, call gdImageTransparent on the tile image and set the transparent color index to -1 to turn off its transparency.

注:gdImageFill は再帰的に処理される。 これは、最も容易な実現方法ではなく、 この実現方法は改良されることが望まれる。 しかし、 スタックが非常に深くなることが可能な場合には、改悪となるだろう。 これは MSDOS と MS Windows 環境での問題である。 (もちろん、適切なスタックがある Unix や NT 環境では、まったく問題ない。)

... 関数の中で ...
gdImagePtr im;
int black;
int white;
int red;
im = gdImageCreate(100, 50);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* カラー red の割り当て */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* だ円を描く */
gdImageArc(im, 50, 25, 98, 48, 0, 360, white);
/* だ円の外側を red で塗りつぶす、背景色の black の部分が塗つぶされる。 */
/* (訳注:だ円の内側を塗りつぶすということで、下の x,y が 50,25 だと分かりやすい気がするのですが?) */
gdImageFill(im, 50, 50, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageSetBrush(gdImagePtr im, gdImagePtr brush) (FUNCTION)
A "brush" is an image used to draw wide, shaped strokes in another image. Just as a paintbrush is not a single point, a brush image need not be a single pixel. Any gd image can be used as a brush, and by setting the transparent color index of the brush image with gdImageColorTransparent, a brush of any shape can be created. All line-drawing functions, such as gdImageLine and gdImagePolygon, will use the current brush if the special "color" gdBrushed or gdStyledBrushed is used when calling them.

gdImageSetBrush is used to specify the brush to be used in a particular image. You can set any image to be the brush. If the brush image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary GIFs to be used as brush images. It also means, however, that you should not set a brush unless you will actually use it; if you set a rapid succession of different brush images, you can quickly fill your color map, and the results will not be optimal.

You need not take any special action when you are finished with a brush. As for any other image, if you will not be using the brush image for any further purpose, you should call gdImageDestroy. You must not use the color gdBrushed if the current brush has been destroyed; you can of course set a new brush to replace it.

... 関数の中で ...
gdImagePtr im, brush;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* Open the brush GIF. For best results, portions of the
    brush that should be transparent (ie, not part of the
    brush shape) should have the transparent color index. */
in = fopen("star.gif", "rb");
brush = gdImageCreateFromGif(in);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
gdImageSetBrush(im, brush);
/* ブラシをつかって左上から右下へ直線を描く */
gdImageLine(im, 0, 0, 99, 99, gdBrushed);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
/* ブラシのイメージを破棄 */
gdImageDestroy(brush);
void gdImageSetTile(gdImagePtr im, gdImagePtr tile) (FUNCTION)
A "tile" is an image used to fill an area with a repeated pattern. Any gd image can be used as a tile, and by setting the transparent color index of the tile image with gdImageColorTransparent, a tile that allows certain parts of the underlying area to shine through can be created. All region-filling functions, such as gdImageFill and gdImageFilledPolygon, will use the current tile if the special "color" gdTiled is used when calling them.

gdImageSetTile is used to specify the tile to be used in a particular image. You can set any image to be the tile. If the tile image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary GIFs to be used as tile images. It also means, however, that you should not set a tile unless you will actually use it; if you set a rapid succession of different tile images, you can quickly fill your color map, and the results will not be optimal.

You need not take any special action when you are finished with a tile. As for any other image, if you will not be using the tile image for any further purpose, you should call gdImageDestroy. You must not use the color gdTiled if the current tile has been destroyed; you can of course set a new tile to replace it.

... 関数の中で ...
gdImagePtr im, tile;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* Open the tile GIF. For best results, portions of the
    tile that should be transparent (ie, allowing the
    background to shine through) should have the transparent 
    color index. */
in = fopen("star.gif", "rb");
tile = gdImageCreateFromGif(in);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
gdImageSetTile(im, tile);
/* タイルをつかって範囲を充たす */
gdImageFilledRectangle(im, 25, 25, 75, 75, gdTiled);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
/* タイルのイメージを破棄 */
gdImageDestroy(tile);
void gdImageSetStyle(gdImagePtr im, int *style, int styleLength) (FUNCTION)
破線、点線、その他の鎖線などを描く際に使われる事が望ましい。 gdImageSetStyle can be used to set any desired series of colors, including a special color that leaves the background intact, to be repeated during the drawing of a line.

To use gdImageSetStyle, create an array of integers and assign them the desired series of color values to be repeated. You can assign the special color value gdTransparent to indicate that the existing color should be left unchanged for that particular pixel (allowing a dashed line to be attractively drawn over an existing image).

Then, to draw a line using the style, use the normal gdImageLine function with the special color value gdStyled.

As of version 1.1.1, the style array is copied when you set the style, so you need not be concerned with keeping the array around indefinitely. This should not break existing code that assumes styles are not copied.

You can also combine styles and brushes to draw the brush image at intervals instead of in a continuous stroke. When creating a style for use with a brush, the style values are interpreted differently: zero (0) indicates pixels at which the brush should not be drawn, while one (1) indicates pixels at which the brush should be drawn. To draw a styled, brushed line, you must use the special color value gdStyledBrushed. For an example of this feature in use, see gddemo.c (provided in the distribution).

gdImagePtr im;
int styleDotted[2], styleDashed[6];
FILE *in;
int black;
int red;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
red = gdImageColorAllocate(im, 255, 0, 0);  
/* 点線を定義する。1ピクセル毎の点線. */
styleDotted[0] = red;
styleDotted[1] = gdTransparent;
/* 破線を定義する。3ピクセルは描かれ、3ピクセルが描かれない。 */
styleDashed[0] = red;
styleDashed[1] = red;
styleDashed[2] = red;
styleDashed[3] = gdTransparent;
styleDashed[4] = gdTransparent;
styleDashed[5] = gdTransparent;
/* 点線を設定する。そのスタイルのピクセル数に注意すること! */
gdImageSetStyle(im, styleDotted, 2);
/* 左上の隅から右下の隅まで、線を描く。 */
gdImageLine(im, 0, 0, 99, 99, gdStyled);
/* こんどは、破線。 */
gdImageSetStyle(im, styleDashed, 6);
gdImageLine(im, 0, 99, 0, 99, gdStyled);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);

問い合わせ関数

int gdImageBlue(gdImagePtr im, int color) (MACRO)
gdImageBlue は指定されたカラーインデックスの blue 要素を返すマクロである。 構造体のメンバーに直接アクセスせずに、このマクロを使用する事。
int gdImageGetPixel(gdImagePtr im, int x, int y) (FUNCTION)
gdImageGetPixel() retrieves the color index of a particular pixel. Always use this function to query pixels; do not access the pixels of the gdImage structure directly.
... 関数の中で ...
FILE *in;
gdImagePtr im;
int c;
in = fopen("mygif.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
c = gdImageGetPixel(im, gdImageSX(im) / 2, gdImageSY(im) / 2);
printf("The value of the center pixel is %d; RGB values are %d,%d,%d\n",
    c, im->red[c], im->green[c], im->blue[c]);
gdImageDestroy(im);
int gdImageBoundsSafe(gdImagePtr im, int x, int y) (FUNCTION)
gdImageBoundsSafe returns true (1) if the specified point is within the bounds of the image, false (0) if not. This function is intended primarily for use by those who wish to add functions to gd. All of the gd drawing functions already clip safely to the edges of the image.
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
if (gdImageBoundsSafe(im, 50, 50)) {
    printf("50, 50 is within the image bounds\n");
} else {
    printf("50, 50 is outside the image bounds\n");
}
gdImageDestroy(im);
int gdImageGreen(gdImagePtr im, int color) (MACRO)
gdImageGreen は指定されたカラーインデックスの green 要素を返すマクロである。 構造体のメンバーに直接アクセスせずに、このマクロを使用する事。
int gdImageRed(gdImagePtr im, int color) (MACRO)
gdImageRed は指定されたカラーインデックスの red 要素を返すマクロである。 構造体のメンバーに直接アクセスせずに、このマクロを使用する事。
int gdImageSX(gdImagePtr im) (MACRO)
gdImageSX はイメージの幅をピクセル単位で返すマクロである。 構造体のメンバーに直接アクセスせずに、このマクロを使用する事。
int gdImageSY(gdImagePtr im) (MACRO)
gdImageSY はイメージ高さをピクセル単位で返すマクロである。 構造体のメンバーに直接アクセスせずに、このマクロを使用する事。

フォントとテキスト操作関数

void gdImageChar(gdImagePtr im, gdFontPtr font, int x, int y, int c, int color) (FUNCTION)
gdImageChar は1文字をイメージに書き込むために使われる。 (複数の文字を書くためには、 gdImageString または gdImageString16 を使用する。) gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant の5つのフォントが gd とともに供給されている。 フォントを使用するためには、 それぞれ "gdfontt.h", "gdfonts.h", "gdfontmb.h","gdfontl.h","gdfontg.h" をインクルードする必要がある。 また (ライブラリを使用していない場合には) 供給されているフォントを使うためには、対応する .c ファイルを Link する必要がある。 5番目のアーギュメントは、 16-bit 符号なし整数として表わされた null で終了する文字列で指定され、 左から右へ、color で指定された色で描画される。 (垂直方向のテキストを描くためには gdImageCharUp を参照の事。) 文字の中で、元の色が残されるピクセルは設定されない。
#include "gd.h"
#include "gdfontl.h"
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* 1文字書き込む */
gdImageChar(im, gdFontLarge, 0, 0, 'Q', white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageCharUp(gdImagePtr im, gdFontPtr font, int x, int y, int c, int color) (FUNCTION)
gdImageCharUp は 90度回転した1文字をイメージに書き込むために使われる。 (複数の文字を書くためには、 gdImageStringUp または gdImageStringUp16 を使用する。) 2番目のアーギュメントはフォント定義構造体へのポインタである; gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant の5つのフォントが gd とともに供給されている。 フォントを使用するためには、 それぞれ "gdfontt.h", "gdfonts.h", "gdfontmb.h","gdfontl.h","gdfontg.h" をインクルードする必要がある。 また (ライブラリを使用していない場合には) 供給されているフォントを使うためには、対応する .c ファイルを Link する必要がある。 5番目のアーギュメントは、 16-bit 符号なし整数として表わされた null で終了する文字列で指定され、 下から上へ 90度回転されて、color で指定された色で描画される。 (水平方向のテキストを描くためには gdImageChar を参照の事。) 文字の中で、元の色が残されるピクセルは設定されない。
#include "gd.h"
#include "gdfontl.h"
... 関数の中で ...
gdImagePtr im;
int black;
int white;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* Draw a character upwards so it rests against the top of the image. */
gdImageCharUp(im, gdFontLarge, 
    0, gdFontLarge->h, 'Q', white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageString(gdImagePtr im, gdFontPtr font, int x, int y, unsigned char *s, int color) (FUNCTION)
gdImageString は複数の文字をイメージに書き込むために使われる。 (1文字書き込むためには gdImageChar を使用する。) 2番目のアーギュメントはフォント定義構造体へのポインタである; gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant の5つのフォントが gd とともに供給されている。 フォントを使用するためには、 それぞれ "gdfontt.h", "gdfonts.h", "gdfontmb.h","gdfontl.h","gdfontg.h" をインクルードする必要がある。 また (ライブラリを使用していない場合には) 供給されているフォントを使うためには、対応する .c ファイルを Link する必要がある。 5番目のアーギュメントは、 16-bit 符号なし整数として表わされた null で終了する文字列で指定され、 左から右へ、color で指定された色で描画される。 (垂直方向のテキストを描くためには gdImageStringUp を参照の事。) 文字の中で、元の色が残されるピクセルは設定されない。
#include "gd.h"
#include "gdfontl.h"
#include <string.h>
... 関数の中で ...
gdImagePtr im;
int black;
int white;
/* 書き込む文字列 */
char *s = "Hello.";
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* 中央に文字列を描く */
gdImageString(im, gdFontLarge,
    im->w / 2 - (strlen(s) * gdFontLarge->w / 2),
    im->h / 2 - gdFontLarge->h / 2,
    s, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageString16(gdImagePtr im, gdFontPtr font, int x, int y, unsigned short *s, int color) (FUNCTION)
gdImageString16 は 16-bit 文字列をイメージに書き込むためにつかわれる。 (1文字を書くためには、gdImageChar を使用する。) 2番目のアーギュメントはフォント定義構造体へのポインタである; gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant の5つのフォントが gd とともに供給されている。 フォントを使用するためには、 それぞれ "gdfontt.h", "gdfonts.h", "gdfontmb.h","gdfontl.h","gdfontg.h" をインクルードする必要がある。 また (ライブラリを使用していない場合には) 供給されているフォントを使うためには、対応する .c ファイルを Link する必要がある。 5番目のアーギュメントは、 16-bit 符号なし整数として表わされた null で終了する文字列で指定され、 左から右に、color で指定された色で描画される。 (垂直方向のテキストを描くためには gdImageStringUp16 を参照の事) 文字の中で、元の色が残されるピクセルは設定されない。

この関数は 256 以上の文字を取り扱うために gd1.3 で追加されて提供された。 より一般的に使用されるルーチンは gdImageString である。

void gdImageStringUp(gdImagePtr im, gdFontPtr font, int x, int y, unsigned char *s, int color) (FUNCTION)
gdImageStringUp は90度回転した複数の文字をイメージに書き込むために使われる。 (1文字を書き込むためには gdImageCharUp を使用する。) 2番目のアーギュメントはフォント定義構造体へのポインタである; gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant の5つのフォントが gd とともに供給されている。 フォントを使用するためには、 それぞれ "gdfontt.h", "gdfonts.h", "gdfontmb.h","gdfontl.h","gdfontg.h" をインクルードする必要がある。 また (ライブラリを使用していない場合には) 供給されているフォントを使うためには、対応する .c ファイルを Link する必要がある。 5番目のアーギュメントは、 16-bit 符号なし整数として表わされた null で終了する文字列で指定され、 下から上へ(90度回転されて)color で指定された色で描画される。 (水平方向のテキストを描くためには gdImageString を参照の事。) 文字の中で、元の色が残されるピクセルは設定されない。
#include "gd.h"
#include "gdfontl.h"
#include <string.h>
... 関数の中で ...
gdImagePtr im;
int black;
int white;
/* 書き込む文字列 */
char *s = "Hello.";
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て) */
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー white の割り当て(red, green, blue すべて最大値) */
white = gdImageColorAllocate(im, 255, 255, 255);    
/* Draw a centered string going upwards. Axes are reversed,
    and Y axis is decreasing as the string is drawn. */
gdImageStringUp(im, gdFontLarge,
    im->w / 2 - gdFontLarge->h / 2,
    im->h / 2 + (strlen(s) * gdFontLarge->w / 2),
    s, white);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageStringUp16(gdImagePtr im, gdFontPtr font, int x, int y, unsigned short *s, int color) (FUNCTION)
gdImageStringUp16 は 16-bit 文字列をイメージに描画するためにつかわれる。 (1文字を書くためには、gdImageChar を使用する。) 2番目のアーギュメントはフォント定義構造体へのポインタである; gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant の5つのフォントが gd とともに供給されている。 フォントを使用するためには、 それぞれ "gdfontt.h", "gdfonts.h", "gdfontmb.h","gdfontl.h","gdfontg.h" をインクルードする必要がある。 また (ライブラリを使用していない場合には) 供給されているフォントを使うためには、対応する .c ファイルを Link する必要がある。 5番目のアーギュメントは、 16-bit 符号なし整数として表わされた null で終了する文字列で指定され、 左から右に、color で指定された色で描画される。 (水平方向のテキストを描くためには gdImageStringUp16 を参照の事。) 文字の中で、元の色が残されるピクセルは設定されない。

この関数は 256 以上の文字を取り扱うために gd1.3 で追加されて提供された。 より一般的に使用されるルーチンは gdImageStringUp である。

カラー操作関数

int gdImageColorAllocate(gdImagePtr im, int r, int g, int b) (FUNCTION)
gdImageColorAllocate は、 指定されたイメージ内の利用可能な最初のカラーインデックスを見つけて、 指定された RGB値(それぞれ 255 が最大値)を設定し、 新しい色のカラーテーブルエントリーのインデックスを返す。 新しいイメージを作成した際に、最初に、この関数を呼び出す事によって、 そのイメージの背景色を設定する事になる。

In the event that all gdMaxColors colors (256) have already been allocated, gdImageColorAllocate will return -1 to indicate failure. (This is not uncommon when working with existing GIF files that already use 256 colors.) Note that gdImageColorAllocate does not check for existing colors that match your request; see gdImageColorExact and gdImageColorClosest for ways to locate existing colors that approximate the color desired in situations where a new color is not available.

... 関数の中で ...
gdImagePtr im;
int black;
int red;
im = gdImageCreate(100, 100);
/* 背景色の割り当て(最初の割り当て)*/
black = gdImageColorAllocate(im, 0, 0, 0);  
/* カラー red の割り当て */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* 左上から右下まで破線を描く */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
int gdImageColorClosest(gdImagePtr im, int r, int g, int b) (FUNCTION)
gdImageColorClosest は、 指定されたイメージの中で定義済みの色から、 指定された RGB 値に最も近い色を探し出し、 そのインデックスを返す。 (Closeness is determined by Euclidian distance, which is used to determine the distance in three-dimensional color space between colors.)

If no colors have yet been allocated in the image, gdImageColorClosest returns -1.

This function is most useful as a backup method for choosing a drawing color when an image already contains gdMaxColors (256) colors and no more can be allocated. (This is not uncommon when working with existing GIF files that already use many colors.) See gdImageColorExact for a method of locating exact matches only.

... 関数の中で ...
gdImagePtr im;
FILE *in;
int red;
/* photo.gif は多色のスキャンされた写真であることにする。 */
in = fopen("photo.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
/* 赤を直接アロケートしてみる */
red = gdImageColorAllocate(im, 255, 0, 0);  
/* 赤をアロケートするのに失敗したら... */
if (red == (-1)) {
    /* 代わりとして 最も近い 色を探す。 */
    red = gdImageColorClosest(im, 255, 0, 0);
}
/* 左上の隅から右下の隅まで破線を描く */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
int gdImageColorExact(gdImagePtr im, int r, int g, int b) (FUNCTION)
gdImageColorExact searches the colors which have been defined thus far in the image specified and returns the index of the first color with RGB values which exactly match those of the request. If no allocated color matches the request precisely, gdImageColorExact returns -1. See gdImageColorClosest for a way to find the color closest to the color requested.
... 関数の中で ...
gdImagePtr im;
int red;
in = fopen("photo.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
/* イメージで赤がすでに使われているならば、そのカラーテーブルを使って、
   すでに定義されている色を使う。   */
red = gdImageColorExact(im, 255, 0, 0);
/* 赤がなかった場合には... */
if (red == (-1)) {
    /* まず、赤を直接アロケートしてみる。 */
    red = gdImageColorAllocate(im, 255, 0, 0);  
    /* 訳注!  ここで、もう1回判定する必要があると思う。下の1行を追加してみた。 */
    if (red == (-1)) {
        /* Out of colors, so find the closest color instead. */
        red = gdImageColorClosest(im, 255, 0, 0);
    }   /* 訳注!  上の訳注で追加した条件のカッコを閉じる。*/
}
/* 左上の隅から右下の隅まで破線を描く */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
int gdImageColorsTotal(gdImagePtr im) (MACRO)
gdImageColorsTotal は、イメージ中に現在アロケートされている色の数を返すマクロである。 この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしない事。
int gdImageColorRed(gdImagePtr im, int c) (MACRO)
gdImageColorRed is a macro which returns the red portion of the specified color in the image. この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしない事。
int gdImageColorGreen(gdImagePtr im, int c) (MACRO)
gdImageColorGreen is a macro which returns the green portion of the specified color in the image. この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしない事。
int gdImageColorBlue(gdImagePtr im, int c) (MACRO)
gdImageColorBlue is a macro which returns the green portion of the specified color in the image. この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしない事。
int gdImageGetInterlaced(gdImagePtr im) (MACRO)
gdImageGetInterlaced は、指定されたイメージがインターレースならば、真 (1)を返す。 インターレースでない場合は、偽 (0)を返すマクロである。 この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしない事。 インターレースのイメージについては gdImageInterlace を参照の事。
int gdImageGetTransparent(gdImagePtr im) (MACRO)
gdImageGetTransparent は、設定されている透過色のカラーインデックスを返すマクロである。 透過色が設定されていない場合には gdImageGetTransparent は -1 を返す。 この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしない事。
void gdImageColorDeallocate(gdImagePtr im, int color) (FUNCTION)
gdImageColorDeallocate marks the specified color as being available for reuse. It does not attempt to determine whether the color index is still in use in the image. After a call to this function, the next call to gdImageColorAllocate for the same image will set new RGB values for that color index, changing the color of any pixels which have that index as a result. If multiple calls to gdImageColorDeallocate are made consecutively, the lowest-numbered index among them will be reused by the next gdImageColorAllocate call.
... 関数の中で ...
gdImagePtr im;
int red, blue;
in = fopen("photo.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
/* Look for red in the color table. */
red = gdImageColorExact(im, 255, 0, 0);
/* If red is present... */
if (red != (-1)) {
    /* Deallocate it. */
    gdImageColorDeallocate(im, red);
    /* Allocate blue, reusing slot in table.
        Existing red pixels will change color. */
    blue = gdImageColorAllocate(im, 0, 0, 255);
} 
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* イメージを破棄 */
gdImageDestroy(im);
void gdImageColorTransparent(gdImagePtr im, int color) (FUNCTION)
gdImageColorTransparent は、 指定されたイメージのカラーインデックスを透過色として設定する。 To indicate that there should be no transparent color, invoke gdImageColorTransparent with a color index of -1.

The color index used should be an index allocated by gdImageColorAllocate, whether explicitly invoked by your code or implicitly invoked by loading an image. In order to ensure that your image has a reasonable appearance when viewed by users who do not have transparent background capabilities, be sure to give reasonable RGB values to the color you allocate for use as a transparent color, even though it will be transparent on systems that support transparency.

... 関数の中で ...
gdImagePtr im;
int black;
FILE *in, *out;
in = fopen("photo.gif", "rb");
im = gdImageCreateFromGif(in);
fclose(in);
/* カラーテーブルから black を探して、透過色にする */
black = gdImageColorExact(im, 0, 0, 0);
/* black があったか? */
if (black != (-1)) {
    /* 透過色とする */
    gdImageColorTransparent(im, black);
} 
/* 新しい透過色をファイルへ保存する */
out = fopen("photo.gif", "wb");
gdImageGif(im, out);
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);

コピーとリサイズ関数

void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h) (FUNCTION)
gdImageCopy は、長方形の範囲を他のイメージからコピーする。 (イメージを伸ばしたり、縮めたりするためのプロセスは、 gdImageCopyResizedを参照の事。)

dst はコピーの目的先となるイメージで、 src はコピー元となるイメージである。 dstXdstY には、 目的先のイメージの中でのコピーする位置を指定する。 srcXsrcY には、 コピー元の左上の隅の位置を指定する。 wh には、長方形の範囲の幅と 高さを指定する。

指定された範囲を、 同じイメージの中の他の位置へコピーする場合には、 その範囲が重なってはならない。 範囲が重なった場合の結果は保証されない。

コピーするイメージ間での重要な注意点: それぞれのイメージは、同じカラーテーブルである必要はない。 コピーする際に、ピクセルに、同じカラーインデックス値を単純に設定するのではない。 gdImageCopy は、 gdImageColorExactを実行する事によって、 コピー元のイメージの範囲内の個々のピクセルと、 目的のイメージ内で一致する RGB 値を探そうとする。 一致する RGB 値がない場合には、gdImageCopy は、 gdImageColorAllocateを 実行して必要とされるカラーを割り当てようとする。 この2つの方法が失敗した場合に、 gdImageCopy は gdImageColorClosest を実行して目的側のイメージの中から コピーしようとするピクセルに、もっとも近い色を探す。

... 関数の中で ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
FILE *in;
FILE *out;
/* 大きなイメージをタイルするための小さな gif をロードする */
in = fopen("small.gif", "rb");
im_in = gdImageCreateFromGif(in);
fclose(in);
/* 両軸が4倍の出力イメージを作成する */
im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4); 
/* 小さなイメージをつかって大きなイメージをタイルする */
for (y = 0; (y < 4); y++) {
    for (x = 0; (x < 4); x++) {
        gdImageCopy(im_out, im_in, 
            x * im_in->sx, y * im_in->sy,
            0, 0,
            im_in->sx, im_in->sy);
    }
}
out = fopen("tiled.gif", "wb");
gdImageGif(im_out, out);
fclose(out);
gdImageDestroy(im_in);
gdImageDestroy(im_out);
void gdImageCopyResized(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int destW, int destH, int srcW, int srcH) (FUNCTION)
gdImageCopyResized は、長方形の範囲を他のイメージからコピーする。 オリジナルの範囲とコピー先の範囲の大きさを XY方向で変える事ができ、 範囲が伸びたり縮んだりしたのに対する適切な結果を得られる。 (サイズの変更をしない単純なコピーについては gdImageCopyを参照の事。)

dst はコピーの目的先となるイメージで、 src はコピー元となるイメージである。 dstXdstY には、 目的先のイメージの中でのコピーする位置を指定する。 dstXdstY には、 目的先のイメージの中でのコピーする位置を指定する。 srcXsrcY には、 コピー元の左上の隅の位置を指定する。 dstWdstH には、 目的先の長方形の範囲の幅と高さを指定する。 srcWsrcH には、 コピー元の長方形の範囲の幅と高さを指定する。 指定された長方形にしたがって、その大きさが調整されてコピーされる。

指定された範囲を、 同じイメージの中の他の位置へコピーする場合には、 その範囲が重なってはならない。 範囲が重なった場合の結果は保証されない。 この問題がおこった場合には、 保持されている中間結果をかき集めたイメージが生成される。

コピーするイメージ間での重要な注意点: それぞれのイメージは、同じカラーテーブルである必要はない。 コピーする際に、ピクセルに、同じカラーインデックス値を単純に設定するのではない。 gdImageCopy は、 gdImageColorExactを実行する事によって、 コピー元のイメージの範囲内の個々のピクセルと、 目的のイメージ内で一致する RGB 値を探そうとする。 一致する RGB 値がない場合には、gdImageCopy は、 gdImageColorAllocateを 実行して必要とされるカラーを割り当てようとする。 この2つの方法が失敗した場合に、 gdImageCopy は gdImageColorClosest を実行して目的側のイメージの中から コピーしようとするピクセルに、もっとも近い色を探す。

... 関数の中で ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
FILE *in;
FILE *out;
/* 小さな gif を読み込んで拡大する */
in = fopen("small.gif", "rb");
im_in = gdImageCreateFromGif(in);
fclose(in);
/* 各軸が4倍の出力イメージを作成する。 */
im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4); 
/* 小さなイメージを4倍にしてコピーする */
gdImageCopyResized(im_out, im_in, 0, 0, 0, 0, 
    im_out->sx, im_out->sy,
    im_in->sx, im_in->sy);   
out = fopen("large.gif", "wb");
gdImageGif(im_out, out);
fclose(out);
gdImageDestroy(im_in);
gdImageDestroy(im_out);

その他の関数

gdImageInterlace(gdImagePtr im, int interlace) (FUNCTION)
gdImageInterlace is used to determine whether an image should be stored in a linear fashion, in which lines will appear on the display from first to last, or in an interlaced fashion, in which the image will "fade in" over several passes. By default, images are not interlaced.

A nonzero value for the interlace argument turns on interlace; a zero value turns it off. Note that interlace has no effect on other functions, and has no meaning unless you save the image in GIF format; the gd and xbm formats do not support interlace.

When a GIF is loaded with gdImageCreateFromGif , interlace will be set according to the setting in the GIF file.

Note that many GIF viewers and web browsers do not support interlace. However, the interlaced GIF should still display; it will simply appear all at once, just as other images do.

gdImagePtr im;
FILE *out;
/* ... イメージを作成または読み込む ... */

/* インターレースに設定する。 */
gdImageInterlace(im, 1); 
/* 出力ファイルを開く */
out = fopen("test.gif", "wb");
/* イメージをセーブする */
gdImageGif(im, out);
fclose(out);
gdImageDestroy(im);

定数(Constants)

gdBrushed (CONSTANT)
gdImageLinegdImageRectangle などの線を描画する関数で、色の指定として使用する。 When gdBrushed is used as the color, the brush image set with gdImageSetBrush is drawn in place of each pixel of the line (the brush is usually larger than one pixel, creating the effect of a wide paintbrush). See also gdStyledBrushed for a way to draw broken lines with a series of distinct copies of an image.
gdMaxColors(CONSTANT)
定数 256。 GIF ファイルの色数の最大値であり GIF の標準と一致している。 また、gd イメージの色数の最大値でもある。
gdStyled (CONSTANT)
gdImageLinegdImageRectangle などの線を描画する関数で、色の指定として使用する。 When gdStyled is used as the color, the colors of the pixels are drawn successively from the style that has been set with gdImageSetStyle. If the color of a pixel is equal to gdTransparent, that pixel is not altered. (This mechanism is completely unrelated to the "transparent color" of the image itself; see gdImageColorTransparent gdImageColorTransparent for that mechanism.) See also gdStyledBrushed.
gdStyledBrushed (CONSTANT)
gdImageLinegdImageRectangle などの線を描画する関数で、色の指定として使用する。 When gdStyledBrushed is used as the color, the brush image set with gdImageSetBrush is drawn at each pixel of the line, providing that the style set with gdImageSetStyle contains a nonzero value (OR gdTransparent, which does not equal zero but is supported for consistency) for the current pixel. (Pixels are drawn successively from the style as the line is drawn, returning to the beginning when the available pixels in the style are exhausted.) Note that this differs from the behavior of gdStyled, in which the values in the style are used as actual pixel colors, except for gdTransparent.
gdDashSize (CONSTANT)
The length of a dash in a dashed line. Defined to be 4 for backwards compatibility with programs that use gdImageDashedLine. New programs should use gdImageSetStyle and call the standard gdImageLine function with the special "color" gdStyled or gdStyledBrushed.
gdTiled (CONSTANT)
gdImageFilledRectangle, gdImageFilledPolygon, gdImageFill, gdImageFillToBorder で通常の色指定と同様に使用する。 gdTiled selects a pixel from the tile image set with gdImageSetTile in such a way as to ensure that the filled area will be tiled with copies of the tile image. See the discussions of gdImageFill and gdImageFillToBorder for special restrictions regarding those functions.
gdTransparent (CONSTANT)
gdImageSetStyle でスタイルを設定する時に、 通常の色指定と同様に使用する。 gdTransparent はイメージの透過色のカラーインデックスではない。 透過色についての機能は、 gdImageColorTransparent を参照の事。

.gd イメージファイルフォーマットについて追加情報

GIF フォーマットの読み書き、X Bitmap フォーマットの読み書きに加えて、 gd には、独自の ".gd" フォーマットを読み書きする機能がある。 このフォーマットは、 一般的な目的で使用することを 意図していない し、 イメージを配布するために使用するべきではない。 このフォーマットは圧縮されていない。 このフォーマットの目的は、 プログラムが、他のイメージを作成するために、 超高速にイメージをローディングする事にある。 プログラムが、出力イメージを作成するために、 変更されない大きな GIF イメージをローディングするケースで、 パフォーマンス向上にとりくむ場合、 .gd フォーマットで読み書きを行う関数 gdImageCreateFromGdgdImageGd の使用を検討するとよいだろう。

"giftogd.c" プログラムは、 .gif ファイルを .gd フォーマットに変換する簡単な方法として配布されている。 少数の使用頻度の高いイメージを超高速にローディングする必要がないならば、 このフォーマットを使う必要はない事を、再度、強調しておく。

お願い! gd の利用例をお知らせください。

gd を利用した時には、ぜひ、お知らせください。 メンテナンスと改良に時間を費やしている私たちに、 正しい事をしていると思えるように、 手を貸してください。 その成果がウェブ上で公開されているのであれば URL をお知らせいただけれる事が、大変な喜びであります。 成果が公開されていないプロジェクトでも、 簡単なメモで、お知らせいただける事を歓迎します。

問題がおこったら

gd について問題があった場合には、遠慮なく作者 Thomas Boutell に連絡してください。 まずは、このマニュアルを注意深く読むこと。

アルファベット順インデックス

gdBrushed | gdDashSize | gdFont | gdFontPtr | gdImage | gdImageArc | gdImageBlue | gdImageBoundsSafe | gdImageChar | gdImageCharUp | gdImageColorAllocate | gdImageColorClosest | gdImageColorDeallocate | gdImageColorExact | gdImageColorTransparent | gdImageCopy | gdImageCopyResized | gdImageCreate | gdImageCreateFromGd | gdImageCreateFromGif | gdImageCreateFromXbm | gdImageDashedLine | gdImageDestroy | gdImageFill | gdImageFillToBorder | gdImageFilledRectangle | gdImageGd | gdImageGetInterlaced | gdImageGetPixel | gdImageGetTransparent | gdImageGif | gdImageGreen | gdImageInterlace | gdImageLine | gdImageFilledPolygon | gdImagePolygon | gdImagePtr | gdImageRectangle | gdImageRed | gdImageSetBrush | gdImageSetPixel | gdImageSetStyle | gdImageSetTile | gdImageString | gdImageString16 | gdImageStringUp | gdImageStringUp16 | gdMaxColors | gdPoint | gdStyled | gdStyledBrushed | gdTiled | gdTransparent

Boutell.Com, Inc.