WICBitmap リファレンス

画像の読み込み・変換・描画・保存を行う WICBitmap オブジェクトのリファレンスです。Windows Imaging Component(WIC)を使っています。

• 関連: te リファレンス、api リファレンス、FolderItems リファレンス、Memory リファレンス
• 作成元: TE/objects.cpp の methodGB[] と CteWICBitmap(Invoke、GetHBITMAP、GetEncoderClsid、CreateStream、RotateFlip など)の実装

記法: P=プロパティ、M=メソッド。メンバー名の照合は大文字小文字を区別しません。

目次

1. 取得方法
2. 読み込み・作成
3. 保存・エンコード
4. サイズ・ピクセル操作
5. 変換・加工
6. フレーム・メタデータ
7. GDI・描画への変換
8. コーデック情報
9. イベント
10. 使用例

1. 取得方法

const image = api.CreateObject("WICBitmap");   // 推奨
const image2 = te.WICBitmap;                   // te.WICBitmap も同じ(参照のたびに新規生成)

te.GdiplusBitmap は旧名で、非推奨です(同じオブジェクトが返ります)。

ルール(重要)

• 読み込み・作成系(From*、Create、Free)を呼ぶと、直前に保持していた画像は必ず破棄されます。失敗した場合も破棄されたままです。
• 読み込み・作成系は、成功すると自分自身(this)を返し、失敗すると空(undefined)を返します。次のように成功を確認してから使ってください。 javascript const image = api.CreateObject("WICBitmap").FromFile(path); if (image) { /* 使える */ }
• 画像を持っていない状態で、GetWidth など画像を必要とするメソッド(保存・サイズ取得・加工・変換・描画)を呼ぶと、何も行わず空を返します(エラーにはなりません)。
• WIC が初期化できない環境では、すべてのメソッドが何も行いません。
• 画素値は 0xAARRGGBB 形式の整数(内部形式は 32bpp BGRA)で扱います。

2. 読み込み・作成

• 読み込み時、JPEG などの EXIF の向き情報(/app1/ifd/{ushort=274})に従って自動的に回転/反転されます。
• FromFile でファイルから読めなかった場合、OnGetAlt(9章)が設定されていて、パスが TE の一時フォルダ(%TEMP%\tablacus\)配下なら、代替パスの取得も試みます。
• 元データ(ストリーム)は、FromSource の bKeepStream が真のとき、複数フレームの画像のとき、またはメインスレッド以外で読み込んだときに保持されます(FromFile / FromStream は通常のメインスレッド読み込みでは保持しません。その場合、Save / DataURI の quality に -2 を指定しても元データは出力できません)。

3. 保存・エンコード

出力形式は、第1引数の文字列から判定します。MIME タイプ("image/png")、ファイル名/拡張子("a.jpg"、".jpg")のどちらも使えます。使えるエンコーダは GetCodecInfo(8章)で調べられます。

type の省略時: 元データを保持している(FromSource の bKeepStream など)場合は元の形式、そうでなければ image/png になります。

quality

4. サイズ・ピクセル操作

• GetPixel / SetPixel / FillRect / Mask / AlphaBlend は、画像を 32bpp BGRA に変換して処理するため、他の形式の画像ではフォーマットが変わります。
• 画素の色の並びは 0xAARRGGBB です。GetRValue 型の COLORREF(0x00BBGGRR)とは並びが異なります。

5. 変換・加工

DrawEx と DrawText、GetHBITMAP / GetHICON は 7章 を参照してください。

6. フレーム・メタデータ

7. GDI・描画への変換

8. コーデック情報

GetCodecInfo(type, mode, array)

WIC に登録されているコーデックの情報を調べ、結果を array(api.Array() や [] など、push メソッドを持つオブジェクト)へ追加します。3個の引数が必要です。

const ar = [];
image.GetCodecInfo(2, 1, ar);   // エンコーダの MIME タイプ一覧
// 結果の内容は環境により異なる(`image/png` などがカンマ区切りで入る)

画像を持っていなくても呼び出せます。

9. イベント

10. 使用例

// ファイルを読み込み、サムネイルを作ってPNGで保存
const image = api.CreateObject("WICBitmap").FromFile("C:\\Pictures\\a.jpg");
if (image) {
    const thumb = image.GetThumbnailImage(128, 128);
    thumb.Save("C:\\Temp\\thumb.png");
}

// DataURI(HTMLに埋め込む)
const uri = image.DataURI("image/jpeg", 80);

// 元の形式のまま取り出す(再エンコードしない)
const src = api.CreateObject("WICBitmap").FromSource(api.SHCreateStreamOnFileEx("C:\\Pictures\\a.gif", 0, 0, false), true);
const raw = src.DataURI("", -2);

// 新規作成してピクセル操作
const bmp = api.CreateObject("WICBitmap").Create(100, 100);
bmp.FillRect(0, 0, 100, 100, 0xFFFF0000);   // 不透明な赤
bmp.SetPixel(50, 50, 0xFF0000FF);           // 青
const c = bmp.GetPixel(50, 50);

// 回転して置き換え(右に90°)
image.RotateFlip(1);

// アイコン/メニュー用のビットマップ
const hbm = image.GetHBITMAP(-2);
// ... 使用後 ...
api.DeleteObject(hbm);

// 利用可能なエンコーダを調べる
const types = [];
image.GetCodecInfo(2, 1, types);

FromSource(api.SHCreateStreamOnFileEx(…)) のように IStream を直接渡す形は、api.SHCreateStreamOnFileEx の引数(api リファレンス)に合わせて調整してください。

関連

• te リファレンス
• api リファレンス
• FolderItems リファレンス
• Memory リファレンス