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

gd のあてにならない抄訳シリーズ第3弾 (^^;;;

未訳の部分は原文のままとしています。
・・・訳文は信頼しないでください。ええと、英語と画像は不得手なんだってばぁ・・・
・・・って、今回、眺めなおしていると gd1.3 の抄訳も、やっぱり、ずいぶん間違ってたところがありましたし(^^;;;
日本語訳の、誤りや疑問点については、 gama <gama@mvg.biglobe.ne.jp> までお知らせください。
・・・ってったって、誤りや疑問点だらけだよなぁ(^^;;;

山賀さん@千葉大総情セによる Version 1.7.x の GD ライブラリで日本語を使う上での 注意事項
gd 1.8.3 とあそぼう!
gd 1.3 のあてにならない参考のための抄訳
まだ作業中です。 このペースだと、今回は完訳がめざせそうな気もしてきました。気力が続くか?

こたさん、りゅうちゃんの励ましに感謝!

りゅうちゃんの推定によると、日本語が読める人が1億人いるとすると、 この抄訳がお役に立てる方が 30 人くらい存在していると思われます。 あとの 28 人の方も、励ましのメールをくださいね(^^;;;


gd 1.8.3

高速イメージ生成用グラフィックスライブラリ

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

はい! 読んでね! gd 1.8.3 は GIF ではなく、PNG, JPEG と WBMP イメージを生成します。 スグレモノです。 PNG は、より小さいフォーマットであり、充分な圧縮が可能です。 JPEG は写真イメージで、よく使用されており、 一般的に普及しているウェブブラウザで PNG よりも高い互換性をもっています。 WBMP はワイヤレス機器(通常のウェブブラウザではない)で使用されています。 既存のコードは gdImageGif に代えて、gdImagePng または gdImageJpeg を 呼ぶように修正する必要があります。 どうか、GIF を取り扱っていた古いバージョンの GD を送付するように依頼しないでください。 Unisys は LZW 圧縮法のアルゴリズムの特許を保有しており、 この圧縮法が GIF イメージの圧縮に使用されています。 最良の解決策は、 PNG と JPEG のような、 法的な問題がなく、よく圧縮される新しいイメージフォーマットへ、できるだけ早く乗り換えることです。

gd 1.8.3 では以下のライブラリがインストールされていることが必要です。

libpng

jpeg-6b 以降

zlib

TrueType フォントを使用したい場合には、さらに、 ヘッダーファイルfreetype.hを含む Freetype libraryがインストールされていなければなりません。 Freetype Home Pageをご覧ください。 なぜ、このサイトが、ときどきダウンしているのかは説明できませんし、 コピーを送ることもできません。

Xpm カラービットマップローディング機能を使いたい場合は、 さらに、X Window System と Xpm ライブラリがインストールされている必要があります。 (Xpm は、たいていの最近の X ディストリビューションに含まれています。)

よくドキュメントを読み、必要なライブラリをインストールしてください。 なぜ png.h がないの? との質問メールを当方へ送らないでください。 より詳しい解説は必要な環境を参照してください。 Thank you!

目次

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

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

 以下の著作権表示は、gd ライブラリの著作権者についての問題を可能なかぎり回避するために、 表示されるべき著作権者をすべて網羅しています。 この著作権表示について問題点を見つけた場合は、 Thomas Boutellまで、 お知らせくださいますようにお願いします。 よろこんで訂正します。

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

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

Portions relating to GD2 format copyright 1999, 2000 Philip Warner.

Portions relating to PNG copyright 1999, 2000 Greg Roelofs.

Portions relating to libttf copyright 1999, 2000 John Ellson (ellson@lucent.com).

Portions relating to JPEG copyright 2000, Doug Becker and copyright (C) 1994-1998, Thomas G. Lane. This software is based in part on the work of the Independent JPEG Group.

Portions relating to WBMP copyright 2000 Maurice Szmurlo and Johan Van den Brande.

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

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

このソフトウェアは "あるがまま(as is)" として提供されています。 著作権所有者は、 このコードと、それに付随するドキュメンテーションに関して、 暗黙に示されている市場価値性や、特定の目的への適合性、および、その他の一切について、 明示、暗黙を問わず一切の保証を負いません。

gd 1.8.3 として提供されているコードには含まれていませんが、 作者は、かつて貢献していただいていた David Koblas,David Rowley および Hutchison Avenue Software Corporation に対して感謝の意を表したいと思います。

著作権表示は以上のとおり

gd とは?

gd は、グラフィックスライブラリです。 あなたのプログラムによって、 直線、円弧、文字、いろんな色、他の画像からのカット&ペースト、 塗りつぶし、などによって、すばやく画像を作成し、 PNG や JPEG file として出力します。 PNG と JPEG が多くのブラウザでインラインイメージとして扱えるフォーマットである ワールドワイドウェブ上でのアプリケーションで特に有用です。

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

gd はすべての魅力的なグラフィック操作のために公開されているものではありません。 gd は何でもかんでもできるグラフィックパッケージになる必要はないし、 そのつもりもありません。 version 1.7.3 では、8bit の 2次元のパッケージとして、 一般的に必要とされる機能を具体化しています。 フルカラーの JPEG と PNG のサポートは、version 2.0 として計画されています。

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

Perl

gd は Perl からも使う事ができます。 Lincoln Stein の好意による GD.pm ライブラリで、 Perl 5.x のクラスのセットとして gd が使われてます。 大変、お勧めです。

Tcl

gd は Tcl からも使うことができます。 John Ellson による ダイナミックにロードされる拡張パッケージ Gdtclft を使用してください。 (Gdtclft2.0 以降のバージョンでは PNG 出力のために gd-1.6 以降のバージョンが必要です。)

Pascal

Pascal 信者へは、Michael Bradbury の gdfp パッケージを検討することをお勧めします。

Haskell

あたらしい gd インターフェイスが Haskell プログラマのために公開されています。

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

gd を操作する簡易なインタープリタが、少なくとも3つ存在しています。 好みの言語で記述したプログラムから要求コマンドを単純なテキストファイルとして出力し、 インタープリタを実行します。

これらのパッケージは、この執筆時点では gd 1.6 以降に対応していません。

What's new in version 1.8.3?

What's new in version 1.8.2?

What's new in version 1.8.1?

What's new in version 1.8?

JPEG についての追加情報

JPEG フォーマットのイメージの読み書き は Doug Becker と Independent JPEG Group / Thomas G. Lane の好意によってサポートされた。 IJG JPEG ソフトウェアの最新版は、 ftp://ftp.uu.net/graphics/jpeg/ で入手できる。 (例えば、jpegsrc.v6b.tar.gz) バージョン 6b 以降の IJG JPEG ソフトウェアを使用しなければならない。 また、JPEG FAQ http://www.faqs.org/faqs/jpeg-faq/ を調べてみるとよい。

What's new in version 1.7.3?

リンカが順序に依存するプラットフォームにおいて、 必要とされるすべてのライブラリをリンクすることを許すように Makefile の修正を試みた。 今度は、たぶん、ちゃんと動くんではないかと思う。

What's new in version 1.7.2?

gdtestttf.c でのポインタが初期化されないバグが修正された。 このバグは、特定のプラットフォームで gdImageStringTTF の呼び出しの終了時にクラッシュを起こしていた。

ドキュメンテーションが修正された。Dohn Arms に感謝。

リンカが順序に依存するプラットフォームにおいて、 すべてのライブラリがリンクすることを許すように Makefile を修正した。

What's new in version 1.7.1?

Makefile 内の些細なバグが修正された、 同様に gdtestttf.c 内での不正確なエラーメッセージも修正された。 やまが まさひと氏に感謝。

What's new in version 1.7?

Version 1.7 では、以下の点が変更されています。

What's new in version 1.6.3?

Version 1.6.3 では、gd_png.c でのメモリーリークが修正された。 このリークは、PNG イメージを書き出す際に、 かなり大量なメモリーをアロケートし、開放していなかった。

What's new in version 1.6.2?

Version 1.6.2 では John Ellson によって、 2つの関数が追加された:

また、このリリースでは構築プロセスが、 GNU autoconf/automake/libtool での記述法に変更され、 静的ライブラリと共有ライブラリの両方(またはどちらか) が構築できるようになりました。

What's new in version 1.6.1?

Version 1.6.1 では、Tom Boutell による多少の修正とともに、 Greg Roelofs による、PNG の読み書きの優れた code を採りいれました。 特に、パレットでないイメージを読み込む code を変更しました (パレットイメージへの変換は上手くなく混乱している)。 現状では gd がサポートしていない透過が指定されたパレットイメージについては、 御勘弁ください(透過機能の指定は単に無視した)。 したがって、この範囲でのいかなるバグも私の責任であり、Greg の責任ではない。

gd 1.6 とは異なり、 指示に従ってすべてをインストールすれば、 ユーザーは、gd 1.6.1 とリンクする際に、 いかなるトラブルも発生しないと考えている。 もし、未定義のシンボル・エラーが発生した場合には、 ライブラリ・ディレクトリーの libpng が旧バージョンでないかを、 しっかり調べて下さい!

What's new in version 1.6?

Version 1.6 では、以下の点が変更されています。

8-bit パレットの PNG イメージのサポートが追加されました。 GIF のサポートが廃止されました。 この変更は、GIF で使用されている LZW 圧縮法に関しての法的な問題を回避するために行われました。 Unisys が LZW圧縮に関する特許を保有しています。 PNG は、いかなる用途においても、大変優れているイメージフォーマットです。 現在 PNG は、Microsoft Internet Explorer と Netscape (最近のリリースによる)の双方でサポートされており、 GD ユーザーが、 法的な問題がないフォーマットで、充分に圧縮されたイメージを得るために、 アップグレードすることを強く推奨します。

What's new in version 1.5?

Version 1.5 では、以下の点が変更されています。
新 GD2 フォーマット
gd フォーマットと比べて大きな改良がなされた GD2 フォーマットは、 大きなイメージを圧縮する為に zlib 圧縮ライブラリを使用する。 ファイルサイズに関して GIF に匹敵する結果が得られるとともに、 巨大なイメージの全てをメモリーに読み込むことなしに、 その一部分へアクセスすることが可能となった。

このフォーマットは、 バージョン番号と基本的な正当性チェックもサポートしており、 従来の GD フォーマットよりも "支持されるべき" である。

ソースファイルの再整理
gd.c は、次の構成へ分割された: io, gif, gd, gd2 とグラフィック関数は、それぞれ分割されたファイルとなった。

拡張 I/O 機能
source/sink 機能は、GD2 ファイルフォーマットをサポートするよう拡張された (seek/tell 関数を必要とする)、また、より一般的な非ファイル I/O が可能になった。

Lincoln Stein による Perl モジュールへのサポートの改善
新しい gdImage*Ptr 関数は、 メモリーのブロック内に選択されたフォーマットを返すようになった。 これは GD perl モジュールから直接使用できる。

追加された関数
gdImageCreateFromGd2Part - イメージの部分の情報検索が可能です(地図のような巨大なイメージに適している)。
gdImagePaletteCopy - 目的側のイメージとソース側のパレットイメージを比較し、最適なパレットをコピーします。
gdImageGd2, gdImageCreateFromGd2 - 新しいフォーマットのサポート。
gdImageCopyMerge - 2つのイメージのマージ(イメージの一部をハイライトにする際に有用)
gdImageCopyMergeGray - gdImageCopyMerge に類似しているが、ソース側のイメージの色調を維持するように努める。
gdImagePngPtr, gdImageJpegPtr, gdImageWBMPPtr, gdImageGdPtr, gdImageGd2Ptr - それぞれのイメージのタイプをメモリーブロックに返す。
gdImageCreateFromPngCtx, gdImageCreateFromGdCtx, gdImageCreateFromGd2Ctx, gdImageCreateFromGd2PartCtx - 新しい I/O コンテキストのサポート。
注: Thomas Boutell へ公正を期して、 上記の全ての機能についてのバグおよび問題点は、おそらく、 Philip Warner へ報告されるべきであろう。

What's new in version 1.4?

Version 1.4 では、以下の点が変更されています。
多角形の塗りつぶしのバグフィックス(再度)
Kirsten Schulz へ感謝、 バージョン1.4は、 バージョン 1.3 を含む従来のリリースで問題で生じていた、 多くのタイプの多角形を塗りつぶすことが出来るようになった。
データの代替入力をサポート
stdio FILE* ストリーム以外から GIF をロードしたい場合に、 新しい gdImageCreateFromPngSource 関数が使用できる。
データの代替出力をサポート
stdio FILE* ストリーム以外へ GIF を出力したい場合に、 新しい gdImagePngToSink 関数が使用できる。 gdImagePngToSink 関数。
GIF を読み込む際の、許容度が向上した。
Version 1.4 は、 あるアニメ GIF 読み込んだ際に、 最初のフレームだけを読み、クラッシュしないようになった。 また、Version 1.4 では、壊れた GIF ファイルを読むときに、 クラッシュしないように、 オーバーフローをテストするコードが追加された。

What's new in version 1.3?

Version 1.3 では、以下の点が変更されています。
Non-LZW-based GIF 圧縮法
Version 1.3 は LZW 圧縮法に代えて、 単純な Run Length Encoding による GIF 圧縮法を内蔵しています。 この圧縮法は、従来の LZW 圧縮法のデコーダとも互換性があります。 (あなたのブラウザは、GIF 画像を見ることができるでしょ?) LZW 圧縮法は Unisys 社の特許です。 gd1.3 で採用されたアプローチは、現在再評価されており、 現在、リリースされている gd では、このアプローチはサポートされていません。 現在のリリースを使用し、PNG イメージを生成することを推奨します。 Hutchison Avenue Software Corporation による RLE Gif コードの提供に感謝します。
8-bit フォントと 8-bit フォントサポート
欧文のサポートを実現しました。 Honza Pazdziora と Jan Pazdziora に感謝! 等幅の X11 フォントを gd のフォントへ変換する Perl スクリプト bdftogd もご覧ください、
16-bit フォントサポート (フォントは含まれていません)
フォントは含まれていませんが、 gdImageString16 と gdImageStringUp16 によって、 256 種以上の文字を扱えるようになりました。
実例/ユーティリティーの "webpng" が改良されました。
"webpng" ユーティリティーが軽く、より有用なアプリケーションとなりました。 Brian Dowling に感謝!
GIF 出力の color resolution field が修正されました。
Thanks to Bruno Aureli.
多角形の塗りつぶしのバグフィックス
Jim Masonの好意により、悪名高い多角形の塗りつぶしのバグに、 1行パッチがあてられました。 この修正で充分だとおもっていますが、しかし、 多角形の塗りつぶしが、まだ正しい動作をしない状況が見つかれば、 ぜひ、その問題点と修正方法を例示するコードを送って下さい。 修正方法を確かめることが重要です。
カラム順から、列順となった。
gd 内部で、ピクセルの配列を、 ピクセルのカラムではなく、 ピクセルの列として表現するようになった。 水平方向に隣接したピクセルが、メモリー上でも互いの隣接する事になり、 圧縮および展開のルーチンのパフォーマンスがわずかながら向上した。 これは、適切に書かれたgdアプリケーションには影響がない、 しかし、ピクセルの配列を直接に操作しているアプリケーションは変更する必要がある。

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 がないのかをインターネットサービスプロバイダへ尋ねてください。

Version 1.6, から、zlib 圧縮用ライブラリと、 libpng ライブラリも必要となった。 Version 1.6.2 からは、libttf ライブラリがインストールされていれば、 アンチエイリアシングな TrueType フォントで文字を描画することが可能になったが、 この機能の使用は任意である。 zlib は、様々なプラットホーム向けとして、 the zlib web site にて公開されています。 libpng も、様々なプラットホーム向けとして、 the PNG web site にて公開されています。

もしも、システムに PNG ビューアーがなければ、 結果をチェックするために、PNG ビューアーも必要となります。 Netscape 4.04 以降と Microsoft Internet Explorer 4.0以降は、双方とも PNG をサポートしています。 また、なんらかの用途のためには、 Lview Pro for Windows や xv for X のようなパッケージがあれば、 より幸せになれるでしょう。 あらゆる、グラフィック能力をもつ近代的なオペレーティングシステム用の PNG ビューアーが存在するので、 特定のシステムについての適切なニュースグループへ助言を求めてみて下さい。

gd の入手方法

By HTTP

By FTP

gd のインストール

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

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

For Unix

cdで、1.8.3 ディレクトリに移動します。 お好きなテキスト・エディターで Makefile を編集し、 設定へ必要な変更を加えて下さい。 特に Xpm, TrueType のサポートが必要な場合には変更が必要です。 次に、"make" とタイプして下さい。 あなたがシステムアドミニストレータであり、 他のプログラムでも gd ライブラリを利用できるようにする場合には、 "make install" とタイプするのもいいでしょう。

エラーになった場合は、INCLUDEDIRS と LIBDIRS の設定へ細心の注意を払って、 もう一度 Makefile を変更します。

リンク時にエラーになる場合には、 Makefile の -l の設定順を、いろいろと入れ替えてみてください。 環境によっては、ライブラリが逆順に並んでいる方がよいかもしれません。

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

お好きなプログラム開発環境でのプロジェクトを作成します。 プロジェクトのディレクトリへ、すべての gd のファイルをコピーして下さい。 プロジェクトへ gd.c を追加してください。 その他、適切なソースファイルを追加してください。 あなたの選んだ C 環境で、プロジェクトを作成する基本的技能の習得は、 あなた次第です。

gd ライブラリと、gd の機能のデモンストレーションプログラムができあがりました。 動作を確認するため、"gddemo" とタイプします。

gddemo が問題なく実行されれば、demoout.png というファイルを作成します。 (注:demoin.png というファイルもあり、 ドキュメンテーションなどと共にパッケージに同梱されています。)

PNG ビューアーで demoout.png を表示して見てください。 128x128 ピクセルのスペースシャトルのイメージ上に、 いろんなグラフィカルな要素が描かれています。

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

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

gd 基礎: gd の使用方法

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

提供されているフォントを使いたい場合には、 gdfontt.h、gdfonts.h、gdfontmb.h、gdfontl.h、および/または gdfontg.h をインクルードしてください。 より印象的な結果のためには、libttf をインストールして、新しい gdImageStringTTF 関数を使って下さい。 提供されている Makefile および/またはライブラリ・ベースの方法をとっていなければ、 確実に、プロジェクトへソースモジュールを含めてください。 (16-bit DOS と Windows などのような 16bit メモリーモデルには大きすぎると思われます。 )

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

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

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

int main() {
	/* イメージを宣言 */
	gdImagePtr im;
	/* 出力ファイルの宣言 */
	FILE *pngout, *jpegout;
	/* カラーインデックスの宣言 */
	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);	

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

	/* JPEG フォーマット用のファイルを同じくオープン  */
	jpegout = fopen("test.jpg", "wb");

	/* イメージをディスクファイルに PNG フォーマットで出力	*/
	gdImagePng(im, pngout);

	/* JPEG のクォリティー設定は規定値を使って、同じイメージをディスクファイルに、
		JPEG フォーマットで出力 */
	gdImageJpeg(im, jpegout, -1);

	/* ファイルをクローズ */
	fclose(pngout);
	fclose(jpegout);

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

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

Webpng: より強力な gd の実例

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

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

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

タイプ(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)
イメージの同じ空間の1点を示す。 gdImagePolygongdImageFilledPolygon によって使われる。
typedef struct {
		int x, y;
} gdPoint, *gdPointPtr;
gdPointPtr (TYPE)
gdPoint 構造体へのポインタ; gdImagePolygongdImageFilledPolygon へのアーギュメントとして渡される。
gdSource (TYPE)
typedef struct {
		int (*source) (void *context, char *buffer, int len);
		void *context;
} gdSource, *gdSourcePtr;
PNG を読み込むための source (情報源)を指定します。 ファイルから PNG を読まずに、 gdImageCreateFromPngSource 関数を使って、 その代替となる独自のインプット手段を用意することができます。 このタイプの適切な使用法の例は、 その関数のドキュメンテーションを参照のこと。
gdSink (TYPE)
typedef struct {
		int (*sink) (void *context, char *buffer, int len);
		void *context;
} gdSink, *gdSinkPtr;
PNG を書き出すための "sink" (掃出し先)を指定します。 PNG をファイルへ書かずに、 gdImagePngToSink 関数を使って、 その代替となる独自のアウトプット手段を用意することができます。 このタイプの適切な使用法の例は、 その関数のドキュメンテーションを参照のこと。

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

gdImageCreate(sx, sy) (FUNCTION)
gdImageCreate はイメージを作成するために使用される。 x,y を指定して gdImageCreate を実行する事によって要求されたイメージを作成する。 gdImageCreate は作成したイメージへの gdImagePtr を返す、 イメージを作成できなかった場合には、NULL が返る。 イメージは gdImageDestroy() によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
im = gdImageCreate(64, 64);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromJpeg(FILE *in) (FUNCTION)
gdImageCreateFromJpegCtx(FILE *in) (FUNCTION)

gdImageCreateFromJpeg は JPEG フォーマットのファイルからイメージをロードする。 すでにオープンされているイメージファイルのポインタを指定して gdImageCreateFromJpeg を実行する。 gdImageCreateFromJpeg は作成したイメージへの gdImagePtr を返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、JPEG イメージではない。) gdImageCreateFromJpeg はファイルをクローズしない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージは gdImageDestroy() によって破棄されなければならない。
gdImagePtr im;
... 関数の中で ...
FILE *in;
in = fopen("myjpeg.jpg", "rb");
im = gdImageCreateFromJpeg(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromPng(FILE *in) (FUNCTION)
gdImageCreateFromPngCtx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromPng は PNG フォーマットのファイルからイメージをロードする。 すでにオープンされているイメージファイルのポインタを指定して gdImageCreateFromPng を実行する。 gdImageCreateFromPng は作成したイメージへの gdImagePtr を返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、PNG イメージではない。) gdImageCreateFromPng はファイルをクローズしない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージは gdImageDestroy() によって破棄されなければならない。
gdImagePtr im;
... 関数の中で ...
FILE *in;
in = fopen("mypng.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromPngSource(gdSourcePtr in) (FUNCTION)
gdImageCreateFromPngSource はファイル以外のデータソースから PNG をロードするために使われる。 プログラマが独自のデータソースを用意する点を除いて、 gdImageCreateFromPng 関数と、ほぼ同様な使用法である。

プログラマは、 アーギュメントとして コンテキストポインタ、バッファ、読み出すバイト数 を受け入れるインプット関数を作成する必要がある。 この関数は、ファイルの終端に達さない限り、 要求されたバイト数まで読みこまなければならず、 この場合には関数はゼロを返す。 エラーが発生した場合には、関数は -1 を返す。 プログラマは、さらに gdSource 構造体を作成し、 インプット関数へのポインタ(source) と プログラマにとって有用な、 なんらかの値へのコンテキストポインタ(context)を設定する。

以下の例では、 gdImageCreateFromPngSource によって、独自のデータソースを作成して、 gdImageCreateFromPng を実装しています。

static int freadWrapper(void *context, char *buf, int len);

gdImagePtr gdImageCreateFromPng(FILE *in)
{
		gdSource s;
		s.source = freadWrapper;
		s.context = in;
		return gdImageCreateFromPngSource(&s);
}

static int freadWrapper(void *context, char *buf, int len)
{
		int got = fread(buf, 1, len, (FILE *) context);
		return got;
}
gdImageCreateFromGd(FILE *in) (FUNCTION)
gdImageCreateFromGdCtx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromGd は gd フォーマットのファイルからイメージをロードする。 すでにオープンされているイメージファイルのポインタを指定して gdImageCreateFromGd を実行する。 gd ファイルフォーマットは、 高速なローディングのための gd 専用のフォーマットである。 (圧縮されていない; 圧縮するためには、PNG か、JPEG を使用する。) gdImageCreateFromGd は作成したイメージへの gdImagePtr を返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、gd フォーマットイメージではない。) gdImageCreateFromGd はファイルをクローズしない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージは gdImageDestroy() によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd", "rb");
im = gdImageCreateFromGd(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromGd2(FILE *in) (FUNCTION)
gdImageCreateFromGd2Ctx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromGd2 は gd2 フォーマットのファイルからイメージをロードする。 すでにオープンされているイメージファイルのポインタを指定して gdImageCreateFromGd2 を実行する。 gd2 ファイルフォーマットは、 高速に大きなイメージの一部をローディングするための gd2 専用のフォーマットである。 (このフォーマットは圧縮されているが、一般的に LZW 圧縮ほどではない。) gdImageCreateFromGd2 は作成したイメージへの gdImagePtr を返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、gd2 フォーマットイメージではない。) gdImageCreateFromGd2 はファイルをクローズしない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージは gdImageDestroy() によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
FILE *in;
in = fopen("mygd.gd2", "rb");
im = gdImageCreateFromGd2(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromGd2Part(FILE *in, int srcX, int srcY, int w, int h) (FUNCTION)
gdImageCreateFromGd2PartCtx(gdIOCtx *in) (FUNCTION)

gdImageCreateFromGd2Part は gd2 フォーマットファイルからイメージの一部をロードする。 gdImageCreateFromGd2 と同じ方法で呼び出すが、 欲しいイメージの source (x, y) と幅と高さ(w, h)を示すパラメータが追加されている。 gdImageCreateFromGd2Part は作成したイメージへの gdImagePtr を返す、 イメージをロードできなかった場合には NULL が返る。 イメージは gdImageDestroy() によって破棄されなければならない。

gdImageCreateFromXbm(FILE *in) (FUNCTION)
gdImageCreateFromXbm は X ビットマップフォーマットのファイルからイメージをロードする。 すでにオープンされているイメージファイルのポインタを指定して gdImageCreateFromXbm を実行する。 gdImageCreateFromXbm は作成したイメージへの gdImagePtr を返す、 イメージをロードできなかった場合には、NULL が返る。 (多くの場合ファイルが壊れているか、X ビットマップフォーマットイメージではない。) gdImageCreateFromXbm はファイルをクローズしない。 イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージは gdImageDestroy() によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
FILE *in;
in = fopen("myxbm.xbm", "rb");
im = gdImageCreateFromXbm(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageCreateFromXpm(char *filename) (FUNCTION)
gdImageCreateFromXpm は XPM X Windows System カラービットマップフォーマットのファイルからイメージをロードする。 この関数は、Makefile 内で HAVE_XPM が選択され、 アプリケーションプログラムに Xpm ライブラリがリンクされている場合にだけ有効である。 ほとんどの gd ファイル関数とは異なり、 Xpm 関数では、ファイルポインタではなくファイル名を指定する。 gdImageCreateFromXpm は作成したイメージへの gdImagePtr を返す、 イメージをロードできなかった場合には NULL が返る。 (多くの場合ファイルが壊れているか XPM ビットマップフォーマットイメージではない。) イメージのサイズは構造体のメンバー sx, sy から知る事ができる。 イメージは gdImageDestroy() によって破棄されなければならない。
... 関数の中で ...
gdImagePtr im;
FILE *in;
in = fopen("myxpm.xpm", "rb");
im = gdImageCreateFromXpm(in);
fclose(in);
/* ... イメージを使う ... */
gdImageDestroy(im);
gdImageDestroy(gdImagePtr im) (FUNCTION)
dImageDestroy はイメージに割りつけられたメモリーを解放するために使用される。 gdImagePtr の変数を新しいイメージを割りあてる前には、 gdImageDestroy を実行しておく事が重要である。
... 関数の中で ...
gdImagePtr im;
im = gdImageCreate(10, 10);
/* ... イメージを使う ... */
/* ここで破棄する */
gdImageDestroy(im);
void gdImageJpeg(gdImagePtr im, FILE *out, int quality) (FUNCTION)
void gdImageJpegCtx(gdImagePtr im, gdIOCtx *out, int quality) (FUNCTION)
gdImageJpeg は指定されたイメージを、 指定された JPEG フォーマットのファイルヘ出力する。 ファイルは、書き込み用にオープンされていなければならない。 MSDOS や全てのバージョンの Windows 環境下では、 ファイルをオープンする時のモードとして、 単に "w" ではなく "wb" を指定する事が重要である。 Unix 環境下で同様な指定をしても悪影響はない。 gdImageJpeg は、ファイルをクローズしない; 各自のコードでクローズしなければならない。

quality (品質値)に負の値が指定された場合には、 IJG JPEG デフォルトの品質値 が使われます。 (一般的に良好な品質であると思われるが、 ほとんどの場合に品質とサイズとトレードオフの関係にある)。 実用上、quality は 0-95 の範囲内になるべきであると思われ、 より高い quality は、 より高い品質と同時に、より大きなイメージサイズとなるとおもわれる。

gdImageInterlace を使用して、 インターレースイメージを設定していた場合には、 この関数はプログレッシブ JPEG を出力する。 いくつかの(たとえばウェブブラウザのような)プログラムは、 プログレッシブ JPEG を表示することができます; 例えば、比較的、低速な通信手段で、 ブラウジングするような場合に、その価値を発揮します。 また、プログレッシブ JPEG はシーケンシャル(非プログレッシブ) JPEG よりも、 わずかにサイズが小さくなります。

... 関数の中で ...
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.jpg", "wb");
/* デフォルトの品質で JPEG を書き出す */
gdImageJpeg(im, out, -1);
/* ファイルをクローズ */
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);
void* gdImageJpegPtr(gdImagePtr im, int *size, int quality) (FUNCTION)(訳注:quality が抜けていたので補った。)
JPEG データのメモリー領域へのポインタを返す点以外は gdImageJpeg とまったく同じである。 必要でなくなった時点で、呼び出した側によって、 このメモリーは開放されなくてはならない。 'size' パラメータには、メモリーのブロックのトータルサイズが返る。
void gdImagePng(gdImagePtr im, FILE *out) (FUNCTION)
gdImagePng は指定されたイメージを、 指定された PNG フォーマットのファイルヘ出力する。 ファイルは、書き込み用にオープンされていなければならない。 MSDOS や全てのバージョンの Windows 環境下では、 ファイルをオープンする時のモードとして、 単に "w" ではなく "wb" を指定する事が重要である。 Unix 環境下で同様な指定をしても悪影響はない。 gdImagePng は、ファイルをクローズしない; 各自のコードでクローズしなければならない。
... 関数の中で ...
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.png", "wb");
/* PNG を書き出す */
gdImagePng(im, out);
/* ファイルをクローズ */
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);
void* gdImagePngPtr(gdImagePtr im, int *size) (FUNCTION)
PNG データのメモリー領域へのポインタを返す点以外は gdImagePng とまったく同じである。 必要でなくなった時点で、呼び出した側によって、 このメモリーは開放されなくてはならない。 'size' パラメータには、メモリーのブロックのトータルサイズが返る。
gdImagePngToSink(gdImagePtr im, gdSinkPtr out) (FUNCTION)
gdImagePngToSink は PNG をファイル以外の データ "sink" (掃出し先) へ書き出すために使用される。 プログラマが独自のデータ掃出し先を用意する点を除いて、 gdImagePng 関数と、ほぼ同様の使用法である。

プログラマは、 アーギュメントとしてコンテキストポインタ、 バッファ、書き出されるバイト数を受け入れるアウトプット関数を作成する必要がある。 この関数は、エラーが発生しない限り、 指定されたバイト数を書き出さなければならず、 書き出したバイト数を返す。 エラーが発生した場合には、関数は -1 を返す。 プログラマは、さらに gdSink 構造体を作成し、 アウトプット関数へのポインタ(sink) と プログラマにとって有用な、 なんらかの値へのコンテキストポインタ(context)を設定する。

以下の例では、 gdImagePngToSink によって、独自のデータ掃出し先を作成して、 gdImagePng を実装している。

static int stdioSink(void *context, char *buffer, int len)
{
	return fwrite(buffer, 1, len, (FILE *) context);
}

void gdImagePng(gdImagePtr im, FILE *out)
{
	gdSink mySink;
	mySink.context = (void *) out;
	mySink.sink = stdioSink;
	gdImagePngToSink(im, &mySink);
}
void gdImageWBMP(gdImagePtr im, int fg, FILE *out) (FUNCTION)
gdImageWBMPCtx(gdIOCtx *out) (FUNCTION)
gdImageWBMP は指定されたイメージを、 指定されたファイルへ WBMP フォーマットで出力する。 ファイルは、書き込み用にオープンされていなければならない。 MSDOS や全てのバージョンの Windows 環境下では、 ファイルをオープンする時のモードとして、 単に "w" ではなく "wb" を指定する事が重要である。 Unix 環境下で同様な指定をしても悪影響はない。 gdImageWBMP は、ファイルをクローズしない; 各自のコードでクローズしなければならない。

WBMPファイルはモノクロだけをサポートしている。 fg アーギュメントによって指定されたカラーインデックスは、 "フォアグラウンド(描画色)" となり、 このカラーのピクセルだけが WBMP ファイルで設定される。 他のすべてのピクセルは "バックグラウンド(背景色)" とみなされる。

... 関数の中で ...
gdImagePtr im;
int black, white;
FILE *out;
/* イメージの作成 */
im = gdImageCreate(100, 100);
/* 背景色のアロケート */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* 長方形を描く */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* バイナリ―モードで出力ファイルをオープン  */
out = fopen("rect.wbmp", "wb");
/* WBMP を書き出す。black をフォアグラウンド(描画色)として */
gdImageWBMP(im, black, out);
/* ファイルをクローズ */
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);
void* gdImageWBMPPtr(gdImagePtr im, int *size) (FUNCTION)
WBMP データのメモリー領域へのポインタを返す点以外は gdImageWBMP とまったく同じである。 必要でなくなった時点で、呼び出した側によって、 このメモリーは開放されなくてはならない。 'size' パラメータには、メモリーのブロックのトータルサイズが返る。
void gdImageGd(gdImagePtr im, FILE *out) (FUNCTION)
gdImageGd は指定されたイメージを、 指定された gd フォーマットのファイルヘ出力する。 ファイルは、書き込み用にオープンされていなければならない。 MSDOS や全てのバージョンの Windows 環境下では、 ファイルをオープンする時のモードとして、 単に "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");
/* gd フォーマットファイルを書き出す */
gdImageGd(im, out);
/* ファイルをクローズ */
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);
void* gdImageGdPtr(gdImagePtr im, int *size) (FUNCTION)
GD データのメモリー領域へのポインタを返す点以外は gdImageGd とまったく同じである。 必要でなくなった時点で、呼び出した側によって、 このメモリーは開放されなくてはならない。 'size' パラメータには、メモリーのブロックのトータルサイズが返る。
void gdImageGd2(gdImagePtr im, FILE *out, int chunkSize, int fmt) (FUNCTION)
gdImageGd2 は指定されたイメージを、 指定された gd2 フォーマットのファイルヘ出力する。 ファイルは、書き込み用にオープンされていなければならない。 MSDOS や全てのバージョンの Windows 環境下では、 ファイルをオープンする時のモードとして、 単に "w" ではなく "wb" を指定する事が重要である。 Unix 環境下で同様な指定をしても悪影響はない。 gdImageGd2 は、ファイルをクローズしない; 各自のコードでクローズしなければならない。

gd2 イメージフォーマットはイメージの一部分を高速に読み書きすることを意図している。 圧縮されたフォーマットであり、 巨大なイメージの中の小さな部分を引き出すように最適化されている。 3番目と4番目のパラメータは 'chunk size' と format resposectively である。 (訳注:format resposectively? ここには、gd.h で define されている GD2_FMT_RAW, GD2_FMT_COMPRESSED が指定でき、圧縮するか否かを指定するようである。)

ファイルは、圧縮されたサブイメージの連続として格納される。 Chunk Size はサブイメージの大きさを決定する。 − 値が 0 の場合には GD ライブラリは規定値を使用する。

圧縮しないフォーマットで GD2 ファイルを格納することも可能である。 その場合には4番目のパラメータに GD2_FMT_RAW を指定する。

... 関数の中で ...
gdImagePtr im;
int black, white;
FILE *out;
/* イメージの作成 */
im = gdImageCreate(100, 100);
/* 背景色のアロケート */
white = gdImageColorAllocate(im, 255, 255, 255);
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0);
/* 長方形を描く */
gdImageRectangle(im, 0, 0, 99, 99, black);
/* バイナリモードで出力ファイルをオープン  */
out = fopen("rect.gd", "wb");
/* gd2 フォーマットファイルを書き出す */
gdImageGd2(im, out, 0, GD2_FMT_COMPRESSED);
/* ファイルをクローズ */
fclose(out);
/* イメージを破棄 */
gdImageDestroy(im);
void* gdImageGd2Ptr(gdImagePtr im, int chunkSize, int fmt, int *size) (FUNCTION)
GD2 データのメモリー領域へのポインタを返す点以外は gdImageGd2 とまったく同じである。 必要でなくなった時点で、呼び出した側によって、 このメモリーは開放されなくてはならない。 'size' パラメータには、メモリーのブロックのトータルサイズが返る。

描画関数

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) に直線を描くために使用される。 直線は、指定されたカラーインデックスによって描かれる。 gdImageColorAllocategdStyledgdBrushedgdStyledBrushed のいずれにかによって返された、 有効なカラーでなくてはならない点に注意する。
... 関数の中で ...
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;
/* Points of polygon */
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 3.1 環境での問題である。 (もちろん、適切なスタックがある Unix や Windows 95/98/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 (だ円)	*/
gdImageFillToBorder(im, 50, 50, white, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* 破棄 */
gdImageDestroy(im);
void gdImageFill(gdImagePtr im, int x, int y, int color) (FUNCTION)
gdImageFill は、イメージの一部を color で指定された色で塗りつぶす、 指定された点から開始し、周囲の始点と同じ色の領域を塗りつぶす。 その内部の色ではなく、指定した境界色によって定義される領域を塗りつぶす方法については、 gdImageFillToBorder を参照のこと。

塗りつぶす色には gdTiled での色が使え、 あるタイルイメージを別のタイルで塗りつぶせる。 しかし、タイルイメージに透過色を使うことはできない。 透過色を含むカラーインデックスで塗りつぶしたい場合には、 タイルイメージにたいして gdImageTransparent をコールし、透過色のカラーインデックスを -1 に設定し、 透過を無効にする。

注:gdImageFill は再帰的に処理される。 これは、最も素朴な実装方法ではなく、 この実装方法は改良されることが望まれるが、しかし、 スタックがとても深くなることが可能な場合には、 改悪となってしまう。 これは MSDOS と MS Windows 3.1 環境での問題である。 (もちろん、適切なスタックがある Unix や Windows 95/98/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);
/* だ円の塗りつぶし。だ円内部の black に代って、
	red で塗りつぶされれる。	*/
gdImageFill(im, 50, 50, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* 破棄 */
gdImageDestroy(im);
void gdImageSetBrush(gdImagePtr im, gdImagePtr brush) (FUNCTION)
"ブラシ" とは、 幅をもった形のストロークで、 他のイメージ上へ描画する際に、 使われるイメージである。 ちょうど、 絵筆が1点でないように、ブラシイメージは一つのピクセルである必要はない。 任意の gd イメージがブラシとして使用できる。 そして、 gdImageColorTransparent でブラシイメージの透過なカラーインデックスを設定することにより、 任意の形状のブラシを作成できる。 gdImageLine および gdImagePolygon 等の、すべての線画関数は、 呼びだす際に、 gdBrushedgdStyledBrushed による特殊な "色" を指定することによりブラシを使用して描画することが可能である。

gdImageSetBrushed は特定のイメージで使われるブラシを指定する。 ブラシとして任意のイメージを設定すること可能である。 最初のイメージとブラシイメージのカラーマップが異なる場合には、 最初のイメージにない色はアロケートされる。 全ての色がアロケートできない場合には、 すでに使われている色のなかから最も近似な色が使用される。 したがって、ブラシイメージとして任意の PNG が使用可能である。 また、実際に使わないブラシは設定するべきではない; 異なるブラシイメージを急速に連続して設定すると、 急速にカラーマップを使い切ることになり、 最適な結果が得られない。

ブラシの使用を終わる際には特別の動作は必要ない。 他のイメージについては、 ブラシイメージをいかなる用途にも使用しなくなった時点で、 gdImageDestroy によって破棄するべきである。 ブラシが破棄されたら gdBrushed で指定された色は使用できない; もちろん、新しいブラシを設定して置き換えることは可能である。

... 関数の中で ...
gdImagePtr im, brush;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* ブラシの PNG を開く。 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.png", "rb");
brush = gdImageCreateFromPng(in);
/* 背景色 (最初のアロケート) */
black = gdImageColorAllocate(im, 0, 0, 0);	
gdImageSetBrush(im, brush);
/* ブラシを使って左上隅から右下隅へ直線を描く */
gdImageLine(im, 0, 0, 99, 99, gdBrushed);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* 破棄 */
gdImageDestroy(im);
/* Destroy the brush image */
gdImageDestroy(brush);
void gdImageSetTile(gdImagePtr im, gdImagePtr tile) (FUNCTION)
"タイル" とは、 ある領域をパターンの繰返しで塗りつぶすためのイメージである。 幅をもった形のストロークで、 他のイメージ上へ描画する際に、 使われるイメージである。 任意の gd イメージがタイルとして使用できる。 そして、 gdImageColorTransparent でタイルメージの透過なカラーインデックスを設定することにより、 任意の形状のタイルを作成できる。 gdImageFill および gdImageFilledPolygon 等の領域を塗つぶす関数は、 呼びだす際に、 gdTiled による特殊な "色" を指定することによりタイルを使用して描画することが可能である。

gdImageSetTile は特定のイメージで使われるタイルを指定する。 タイルとして任意のイメージを設定すること可能である。 最初のイメージとタイルイメージのカラーマップが異なる場合には、 最初のイメージにない色はアロケートされる。 全ての色がアロケートできない場合には、 すでに使われている色のなかから最も近似な色が使用される。 したがって、タイルイメージとして任意の PNG が使用可能である。 また、実際に使わないタイルは設定するべきではない; 異なるタイルイメージを急速に連続して設定すると、 急速にカラーマップを使い切ることになり、 最適な結果が得られない。

タイルの使用を終わる際には特別の動作は必要ない。 他のイメージについては、 タイルイメージをいかなる用途にも使用しなくなった時点で、 gdImageDestroy によって破棄するべきである。 タイルが破棄されたら gdTiled で指定された色は使用できない; もちろん、新しいタイルを設定して置き換えることは可能である。

... 関数の中で ...
gdImagePtr im, tile;
FILE *in;
int black;
im = gdImageCreate(100, 100);
/* Open the tile PNG. 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.png", "rb");
tile = gdImageCreateFromPng(in);
/* 背景色 (最初のアロケート) */
black = gdImageColorAllocate(im, 0, 0, 0);	
gdImageSetTile(im, tile);
/* Fill an area using the tile. */
gdImageFilledRectangle(im, 25, 25, 75, 75, gdTiled);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* 破棄 */
gdImageDestroy(im);
/* Destroy the tile image */
gdImageDestroy(tile);
void gdImageSetStyle(gdImagePtr im, int *style, int styleLength) (FUNCTION)
破線、点線、その他の鎖線などを描く際に使われる事が望ましい。 gdImageSetStyle は線を描画する際に繰り返される、 いくつかの要求された色の並びを設定する際に使用する事ができる。 背景をそのままにしておく特殊な色も指定することができる。

gdImageSetStyle を使うためには、 整数の配列を作成し、繰返しのカラー値の並びを割り当てる。 あるピクセルの既存のカラーを変えないために、 特殊な色として gdTransparent を割り当てることができる (既存のイメージ上に破線を目立つように描く場合など)。

したがって、 スタイルを使用して線を描くためには、 gdStyled で指定した特殊な色を使用して、 通常の gdImageLine 関数を使用する。

バージョン1.1.1 以降では、 スタイルを設定する際にスタイル配列がコピーされる、 したがって、配列を無期限に保持する必要はない。 これは、 スタイルはコピーされないことを前提に作成されていた従来のコードとも矛盾しない。

連続的なストロークに代えて、 断続的な繰返しのブラシ・イメージを使用するように、 スタイルとブラシを結びつけることができる。 ブラシと共に使用するスタイルを作成する際には、 そのスタイル値により相違が決定される: ゼロ (0) は描画されないピクセルを示し、 (1) は描画されるピクセルを示す。 スタイルとブラシで指定される線を描く為には、 特殊なカラー値 gdStyledBrushed を使用する。 この機能の使用例については、gddemo.c (同梱されている) を参照のこと。

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() は、特定のピクセルのカラーインデックスを検索する。 ピクセルを問合わせるには、常にこの関数を使用すること; gdImage 構造体の pixels を直接アクセスしないこと。
... 関数の中で ...
FILE *in;
gdImagePtr im;
int c;
in = fopen("mypng.png", "rb");
im = gdImageCreateFromPng(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 を使用する。 gd-1.6.2. で新たに登場した gdImageStringTTF も参照のこと。) 2番目のアーギュメントはフォント定義構造体へのポインタである; gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant の5つのフォントが gd とともに提供されている。 フォントを使用するためには、それぞれ "gdfontt.h", "gdfonts.h", "gdfontmb.h","gdfontl.h","gdfontg.h" をインクルードする必要がある。 また (ライブラリによる方法を使用していない場合には) 提供されているフォントを使うためには、 対応する .c ファイルをリンクする必要がある。 5番目のアーギュメントとして指定された、 文字が、左から右へ 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ファイルをリンクする必要がある。 5番目のアーギュメントとして指定された、 文字が、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);	
/* 上方向に向かって1文字を描く、したがって、イメージの上辺にかかる。 */
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番目のアーギュメントとして指定された、 null で終了する文字列が、 左から右へ、color で指定された色で描かれる。 (垂直方向のテキストを描くためには gdImageStringUp を参照のこと。 gd-1.6.2. で新たに登場した gdImageStringTTF も参照のこと。) それぞれの文字によって設定されなかったピクセルでは、元の色が残る。
#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);	
/* 真ん中に文字列を描く (訳注:原文の im->w, im->h を im->sx, im->sy に修正) */
gdImageString(im, gdFontLarge,
	im->sx / 2 - (strlen(s) * gdFontLarge->w / 2),
	im->sy / 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 ファイルをリンクする必要がある。 5番目のアーギュメントとして指定された、null で終了する 16-bit 符号なし整数で記述される文字列が、 左から右へ、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 ファイルをリンクする必要がある。 5番目のアーギュメントは、 null で終了する文字列で指定され、 下から上へ(90度回転されて)color で指定された色で描画される。 (水平方向のテキストを描くためには gdImageString を参照の事。) それぞれの文字によって設定されなかったピクセルでは、元の色が残る。
#include "gd.h"
#include "gdfontl.h"
#include <string.h>
... 関数の中で ...
gdImagePtr im;
int black;
int white;
/* String to draw. */
char *s = "Hello.";
im = gdImageCreate(100, 100);
/* 背景色 (最初のアロケート) */
black = gdImageColorAllocate(im, 0, 0, 0);	
/* カラー white をアロケート (red, green, blue すべて最小値)  */
white = gdImageColorAllocate(im, 255, 255, 255);	
/* 上に向かう文字列を真ん中に描く。軸は逆になる。
	文字列が描かれる際には、Y 軸は減少する。 */
/* (訳注:原文の im->w, im->h を im->sx, im-sy に修正) */
gdImageStringUp(im, gdFontLarge,
	im->sx / 2 - gdFontLarge->h / 2,
	im->sy / 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 ファイルをリンクする必要がある。 16-bit 符号なし整数として表わされた null で終了する文字列で指定され、 下から上へ(90度回転されて)color で指定された色で描画される。 (水平方向のテキストを描くためには gdImageStringUp16 を参照の事。) それぞれの文字によって設定されなかったピクセルでは、元の色が残る。

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

char *gdImageStringTTF(gdImagePtr im, int *brect, int fg, char *fontname, double ptsize, double angle, int x, int y, char *string) (FUNCTION)
gdImageStringTTF は、 FreeType ライブラリを使用し、 ユーザーの用意した TrueType フォントによって、 アンチエイリアスな文字による文字列を描画する。 TrueType fonts は供給されません。 それは、全てあなた次第です。 アンチエイリアスな文字列とは、"ギザギザ" がないことを意味します。 fontname には TrueType フォントファイルのフルパス名を指定します。 文字列は、任意のサイズ(ptsize) と任意の角度(angle ラジアンで指定)での回転が可能である。

int brect[8] として与えられた配列に、 gdImageStringTTF によって、 境界の長方形の四隅の座標の 8つの要素が設定される。
0 左下隅、X 位置
1 左下隅、Y 位置
2 右下隅、X 位置
3 右下隅、Y 位置
4 右上隅、X 位置
5 右上隅、Y 位置
6 左上隅、X 位置
7 左上隅、Y 位置

各座標はテキストの角度に影響されていない、 したがって、"左上" は、テキストを水平に見たときの左側の上の隅を意味する。

gdImagePtr へ NULL を指定すると、 レンダリングされずに長方形の範囲が取得される。 長方形の境界の計算によってレンダリングの一部がキャッシングされるので、 同じ文字列でのレンダリングが続く場合には、比較的安価な操作である。

文字列の色は gf カラーインデックスでレンダリングされる。 アンチエイリアシングを無効にするためにはカラーインデックスに負の値を指定する。

文字列は、"&#192;" のような UTF-8 シーケンスを含んでいてもよい。

gdImageStringTTF は、成功時には NLLL char* を返す、 失敗時にはエラー文字列が返る。

#include "gd.h"
#include <string.h>
... 関数の中で ...
gdImagePtr im;
int black;
int white;
int brect[8];
int x, y;
char *err;

char *s = "Hello."; /* 描画する文字列。 */
double sz = 40.;
char *f = "/usr/local/share/ttf/Times.ttf";  /* ユーザーが用意したフォント */

/* brect にイメージのサイズが取得される。 */
err = gdImageStringTTF(NULL,&brect[0],0,f,sz,0.,0,0,s);
if (err) {fprintf(stderr,err); return 1;}

/* 多少の余白を追加して文字列に対して充分なイメージを作成する */
x = brect[2]-brect[6] + 6;
y = brect[3]-brect[7] + 6;
im = gdImageCreate(x,y);

/* 背景色 (最初のアロケート) */
white = gdImageColorResolve(im, 255, 255, 255);
black = gdImageColorResolve(im, 0, 0, 0);

/* ストリングを指定する、ストリングの中心へのオフセットオリジン */
/* 左上での gd オリジンから y を下方向に増やして、
   調整された左上の座標を使用する事に注意			*/
x = 3 - brect[6];
y = 3 - brect[7];
err = gdImageStringTTF(im,&brect[0],black,f,sz,0.0,x,y,s);
if (err) {fprintf(stderr,err); return 1;}

/* stdout へ書き出す */
gdImagePng(im, stdout);

/* 破棄 */
gdImageDestroy(im);

カラー操作関数

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

gdMaxColors (256) 色がすでにアロケートされている場合には gdImageColorAllocate は不成功を示す -1 を返す。 (既存の PNG ファイルでは、すでに 256色を使っているのは珍らしいことではない。) 注 gdImageColorAllocate は要求された色と一致する定義済の色をチェックしない; 新しいカラーが利用できない場合に、 定義済の色から、要求された色に近似する色を探す方法に関しては gdImageColorExact, gdImageColorClosest, gdImageColorClosestHWB を参照のこと。 また、gd-1.6.2 で新登場の gdImageColorResolve も参照のこと。

... 関数の中で ...
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 値に最も近い色を探し出し、 そのインデックスを返す。 (三次元の色空間内でのユークリッド幾何学的距離によって近似が決定される)

イメージの中に近似色がアロケートされていない場合には、 gdImageColorClosest は -1 を返す。

この関数は、イメージ内で、 すでに gdMaxColors (256)色 が使われていて、これ以上の描画色を追加できない場合に、 描画色を選択する代替策である。 (すでに多くの色を使っている PNG ファイルでは珍しいことではない。) gdImageColorExact 定義済のカラーから一致するカラーを探す方法については、 gdImageColorExact を参照のこと。

... 関数の中で ...
gdImagePtr im;
FILE *in;
int red;
/* photo.png は多色のスキャンされた写真であることとする */
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* red を直接アロケートしてみる */
red = gdImageColorAllocate(im, 255, 0, 0);	
/* red のアロケートに失敗した場合に... */
if (red == (-1)) {
	/* 代わりとして 最も近い 色を探す。 */
	red = gdImageColorClosest(im, 255, 0, 0);
}
/* 左上隅から右下隅まで破線を描く */
gdImageDashedLine(im, 0, 0, 99, 99, red);
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* 破棄 */
gdImageDestroy(im);
int gdImageColorClosestHWB(gdImagePtr im, int r, int g, int b) (FUNCTION)
gdImageColorClosestHWB は、指定されたイメージの中で定義済みの色から、 指定された RGB 値に、 色調(hue)、白さ(whiteness)、黒さ(blackness)にもとづいて 最も近い色を探し出し、 そのインデックスを返す。 この方法は、 gdImageColorClosest で使われているユークリッド幾何学的近似による方法よりも優れている。

イメージの中に近似色がアロケートされていない場合には、 gdImageColorClosestHWB は -1 を返す。

この関数は、イメージ内で、 すでに gdMaxColors (256)色 が使われていて、これ以上の描画色を追加できない場合に、 描画色を選択する代替策である。 (すでに多くの色を使っている PNG ファイルでは珍しいことではない。) gdImageColorExact 定義済のカラーから一致するカラーを探す方法については、 gdImageColorExact を参照のこと。

... 関数の中で ...
gdImagePtr im;
FILE *in;
int red;
/* photo.png は多色のスキャンされた写真であることとする */
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* red を直接アロケートしてみる */
red = gdImageColorAllocate(im, 255, 0, 0);	
/* red のアロケートに失敗した場合に... */
if (red == (-1)) {
	/* 代わりとして 最も近い 色を探す。 */
	red = gdImageColorClosestHWB(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 は、 指定されたイメージ内の定義済の色を検索して、 RGB 値が正確に合致する最初のカラーインデックスを返す。 合致する色がアロケートされていない場合には、 gdImageColorExact は -1 を返す。 近似色を探す方法については、 gdImageColorClosest を参照のこと。
... 関数の中で ...
gdImagePtr im;
int red;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* イメージで赤がすでに使われているならば、そのカラーテーブルを使って、
	すでに定義されている色を使う。	 */
/* red は定義済みか? */
red = gdImageColorExact(im, 255, 0, 0);
/* red が定義済みでなかったときは... */
if (red == (-1)) {
	/* 次善: red を直接アロケートする。 */
	red = gdImageColorAllocate(im, 255, 0, 0);	
	/* 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 gdImageColorResolve(gdImagePtr im, int r, int g, int b) (FUNCTION)
gdImageColorResolve は、 指定されたイメージ内の定義済の色を検索して、 RGB 値が正確に合致する最初のカラーインデックスを返す。 合致する色がアロケートされていない場合には、 gdImageColorResolve は指定された色をアロケートする。 カラーテーブルに空きスペースがなく、指定された色をアロケートできない場合には、 gdImageColorResolve は近似色を返す (gdImageColorClosest でのように)。 この関数は、常にカラーインデックスを返す。
... 関数の中で ...
gdImagePtr im;
int red;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* イメージで red がすでに使われているならば、そのカラーテーブルを使って、
	すでに定義されている色を使う。	 */
/* red か、その近似色のインデックスを取得する */
red = gdImageColorResolve(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 は、イメージ中の指定された色の red 要素を返すマクロである。 この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしないこと。
int gdImageColorGreen(gdImagePtr im, int c) (MACRO)
gdImageColorGreen は、イメージ中の指定された色の green 要素を返すマクロである。 この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしないこと。
int gdImageColorBlue(gdImagePtr im, int c) (MACRO)
gdImageColorBlue は、イメージ中の指定された色の blue 要素を返すマクロである。 この情報を得るためには、このマクロを使用し、構造体のメンバーに直接アクセスしないこと。
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 は指定されたカラーを再使用が可能なようにマークします。 イメージの中で他のカラーインデックスが使用されているかは関知しません。 この関数への呼びだしの後に、 同じイメージに gdImageColorAllocate を呼び、 そのカラーインデックスへ新しいRGB値を設定すると、 結果として、そのインデックスを持っている全てのピクセルの色が変わります。 gdImageColorDeallocate が連続して複数回実行される場合には、 インデックス中でもっとも小さい番号のインデックスが、 次の gdImageColorAllocate で再使用される。
... 関数の中で ...
gdImagePtr im;
int red, blue;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* カラーテーブル内の red を探す。 */
red = gdImageColorExact(im, 255, 0, 0);
/* red があれば... */
if (red != (-1)) {
	/* 破棄 */
	gdImageColorDeallocate(im, red);
	/* blue をアロケート、 テーブルのスロットを再利用。
	   既存の red のピクセルの色が変わる。 */
	blue = gdImageColorAllocate(im, 0, 0, 255);
}
/* ... イメージに何らかの操作をする。ファイルにセーブするなど... */
/* 破棄 */
gdImageDestroy(im);
void gdImageColorTransparent(gdImagePtr im, int color) (FUNCTION)
gdImageColorTransparent は指定されたイメージ内の指定されたカラーインデックスを 透過カラーインデックスに設定する。 透過カラーがないことを示すためには、 カラーインデックスに -1 を指定して gdImageColorTransparent を呼びだす。 注:JPEG イメージは透過をサポートしていない。 したがって、 JPEG イメージに書き出す場合には、この設定はなんの効果ももたない。

カラーインデックスは、 各自のコードによって明白に実行されるか、 イメージをロードすることによって暗黙に実行されるかのどちらかで gdImageColorAllocate がアロケートしたインデックスでなければならない。 In order to ensure that your image has a reasonable appearance when viewed by users who do not have transparent background capabilities (or when you are writing a JPEG-format file, which does not support transparency), 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 PNG transparency.

... 関数の中で ...
gdImagePtr im;
int black;
FILE *in, *out;
in = fopen("photo.png", "rb");
im = gdImageCreateFromPng(in);
fclose(in);
/* カラーテーブルの中の black を探し、透過に設定する。 */
black = gdImageColorExact(im, 0, 0, 0);
/* black があれば... */
if (black != (-1)) {
	/* 透過にする */
	gdImageColorTransparent(im, black);
}
/* 新しい透過のイメージをファイルに書き戻す。 */
out = fopen("photo.png", "wb");
gdImagePng(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)
dImageCopy は、 長方形の範囲を他のイメージからコピーする。 (プロセスで、イメージを伸ばしたり縮めたりするためには gdImageCopyResized を参照のこと。)

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

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

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

... 関数の中で ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
FILE *in;
FILE *out;
/* 大きなイメージをタイルするための小さな png をロードする */
in = fopen("small.png", "rb");
im_in = gdImageCreateFromPng(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.png", "wb");
gdImagePng(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 に目的先のイメージの中でのコピーする位置を指定する。 srcXsrcY にコピー元の左上の隅の位置を指定する。 dstWdstH には、 目的先の長方形の範囲の幅と高さを指定する。 srcWsrcH には、 コピー元の長方形の範囲の幅と高さを指定する。 指定された長方形にしたがって、その大きさが調整されてコピーされる。

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

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

... 関数の中で ...
gdImagePtr im_in;
gdImagePtr im_out;
int x, y;
FILE *in;
FILE *out;
/* 大きなイメージをタイルするための小さな png をロードする */
in = fopen("small.png", "rb");
im_in = gdImageCreateFromPng(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.png", "wb");
gdImagePng(im_out, out);
fclose(out);
gdImageDestroy(im_in);
gdImageDestroy(im_out);
void gdImageCopyMerge(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h, int pct) (FUNCTION)
gdImageCopyMerge は最後のパラメータで示された量によって2つのイメージを 'マージ(merges)' すること以外は、 gdImageCopy と同じである。 最後のパラメータが 100 であれば、gdImageCopy と同じに機能する - コピー元のイメージによって、目的先のピクセルを置き換える。

パラメータ pct が 100 未満であれば、 2つのイメージがマージされる。 pct = 0 では、いかなる動作もしない。

この機能は、単色のカラーを pct = 50 でマージすることにより、 イメージのある部分を 'ハイライト' にする場合に、最も有用である。

... 関数の中で ...
gdImageCopyMerge(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
void gdImageCopyMergeGray(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h, int pct) (FUNCTION)
gdImageCopyMergeGray は、 マージする際に、 コピーの前に、目的先のピクセルを グレースケールに変換する事によって、 コピー元の色調を維持すること以外は、 gdImageCopyMerge と同じである。
... 関数の中で ...
gdImageCopyMergeGray(im_out, im_in, 100, 200, 0, 0, 30, 50, 50);
void gdImagePaletteCopy(gdImagePtr dst, gdImagePtr src) (FUNCTION)
コピー元のパレットの色と 目的先のイメージの色が一致するように、 あるイメージから他のイメージへ、パレットをコピーする。

その他の関数

int gdImageCompare(gdImagePtr im1, gdImagePtr im2) (FUNCTION)
gdImageCompare は2つのイメージの違いを返す。 違いを示す値は gd.h で宣言されているが、 もっとも重要なのは GD_CMP_IMAGE であり、 そのイメージが表示されたときに、 実際に異なるように見えることを示す。 重要性は低くなるが、 他に、 パレットエントリーの関係が違っていることが示される。 他にも、 透過色が違ったり、透過色が使われていないために表示が違うことが示される。
... 関数の中で ...
cmpMask = gdImageCompare(im1, im2);
gdImageInterlace(gdImagePtr im, int interlace) (FUNCTION)
gdImageInterlace は、 イメージが、 ラインがはじめから終わりまでディスプレイに現れるリニアな様式で保存されるか、 ラインを数本あけて徐々に現れるインターレースな様式で保存されるかを決定する。 規定値では、イメージはノン・インターレースである。 (JPEG イメージを書き出す際に、 インターレースでは、 表示の質を徐々に向上しながら再現される プログレッシブ JPEG ファイルを生成することを意味する。 ノン・インターレースでは、通常の [シーケンシャル] JPEG データストリームとなる。)

アーギュメント interlace の 0 以外の値は、 インターレースを設定する; 値が 0 の時はインターレースを無効にする。 注: このインターレースは、他の関数には影響がなく、 PNG または JPEG フォーマットにセーブしなければ何の意味も持たない。 (gd と xbm フォーマットはインターレースをサポートしていない。)

PNG が gdImageCreateFromPng でロードされるか、 gdImageCreateFromJpeg で JPEG がロードされる際には、 その PNG または JPEG ファイル内の設定に従ってインターレースが設定される。

多くの PNG, JPEG ビューアとウェブブラウザはインターレースや プログレッシブ JPEG のインクリメンタルな表示をサポート してない 点に注意すること。 その場合でも、インターレース PNG、プログレッシブ JPEG は静的に表示される; 他の画像と同様に一度に表示される。

gdImagePtr im;
FILE *out;
/* ... イメージを作成するか読み込む ... */

/* インターレースに設定する。 */
gdImageInterlace(im, 1);
/* 出力ファイルを開く */
out = fopen("test.png", "wb");
/* イメージをセーブする  -- gdImageJpeg も使用できる */
gdImagePng(im, out);
fclose(out);
gdImageDestroy(im);

定数(Constants)

gdBrushed (CONSTANT)
Used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. 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。 PNG ファイルの色数の最大値であり PNG の標準と一致している。 また、gd イメージの色数の最大値でもある。
gdStyled (CONSTANT)
Used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. 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)
Used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. 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. gdImageFill および gdImageFillToBorder では特別の制限があるので、 それらの関数での検討を参照のこと。
gdTransparent (CONSTANT)
gdImageSetStyle でスタイルを設定する時に、通常の色指定と同様に使用する。 gdTransparent はイメージの透過色のカラーインデックスではない。 透過色についての機能は、 gdImageColorTransparent を参照する事。

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

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

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

.gd2 イメージファイルフォーマットについて

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

.png ファイルを .gd2 フォーマットへ変換する簡単な方法 としてプログラム "pngtogd2.c" が提供されています。

gdIOCtx 構造体について

GD Version 1.5 で IOCtx 構造体による新しい I/O のスタイルが加わりました。 (最新バージョンは gd_io.h で見つけることができます。):
typedef struct gdIOCtx {
		int 	(*getC)(struct gdIOCtx*);
		int 	(*getBuf)(struct gdIOCtx*, void*, int);

		void	 (*putC)(struct gdIOCtx*, int);
		int 	(*putBuf)(struct gdIOCtx*, const void*, int);

		int 	(*seek)(struct gdIOCtx*, const int);
		long	(*tell)(struct gdIOCtx*);

		void	(*free)(struct gdIOCtx*);

} gdIOCtx;
従来のバージョンでファイルでの受け入れていた関数のほとんどに、 相当する I/O コンテキストを受け取る関数が用意されました。 これらの関数は 'Ctx' サフィックスを持っています。

すべての I/O を実行するために、Ctx ルーチンは、 I/O コンテキストでの関数ポインタを使います。 たとえば、 I/O コンテキストがどのように実装されているかを io_files.c (ファイルルーチンへのラッパーを提供しています) や io_dp.c (メモリー上のストレージとして実装されています) の中で見ることができます。

限定された使い方しかされない事がわかっている場合には、 ある I/O コンテキストに、全ての関数を実装する必要はない。 執筆時点 (Version 1.6.1、1999年7月) で、判明している必要な関数は:

全ての場合に 'free' が必要であり、
コンテキストによって読み込む場合には'getC' と 'getBuf' を必要とし、
コンテキストによって書き出す場合には'putC' と 'putBuf' を必要とする。
gdCreateFromGd2Part が呼ばれる場合にはさらに 'seek' と 'tell' も必要とする。
gdImageGd2 が呼ばれる場合にはさらに 'seek' と 'tell' も必要とする。

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

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

問題がおこったら

gd について問題があった場合には、遠慮なく作者 Thomas Boutell に連絡してください。 gd2 フォーマットに関する問題については、 Philip Warner. へ連絡してください。

まずは、このマニュアルを注意深く読むこと。

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

gdBrushed | gdDashSize | gdFont | gdFontPtr | gdImage | gdImageArc | gdImageBlue | gdImageBoundsSafe | gdImageChar | gdImageCharUp | gdImageColorAllocate | gdImageColorClosest | gdImageColorClosestHWB | gdImageColorDeallocate | gdImageColorExact | gdImageColorResolve | gdImageColorTransparent | gdImageCompare | gdImageCopy | gdImageCopyMerge | gdImageCopyMergeGray | gdImageCopyResized | gdImageCreate | gdImageCreateFromGd | gdImageCreateFromGd2 | gdImageCreateFromGd2Part | gdImageCreateFromJpeg | gdImageCreateFromPng | gdImageCreateFromPngSource | gdImageCreateFromXbm | gdImageCreateFromXpm | gdImageDashedLine | gdImageDestroy | gdImageFill | gdImageFilledPolygon | gdImageFilledRectangle | gdImageFillToBorder | gdImageGd | gdImageGd2 | gdImageGd2Ptr | gdImageGdPtr | gdImageGetInterlaced | gdImageGetPixel | gdImageGetTransparent | gdImageGreen | gdImageInterlace | gdImageJpeg | gdImageJpegPtr | gdImageLine | gdImagePaletteCopy | gdImagePng | gdImagePngPtr | gdImagePngToSink | gdImagePolygon | gdImagePtr | gdImageRectangle | gdImageRed | gdImageSetBrush | gdImageSetPixel | gdImageSetStyle | gdImageSetTile | gdImageString | gdImageString16 | gdImageStringTTF | gdImageStringUp16 | gdImageStringUp | gdImageWBMP | gdImageWBMPPtr | gdMaxColors | gdPoint | gdStyled | gdStyledBrushed | gdTiled | gdTransparent

Boutell.Com, Inc.