GetGlyphOutlineA

関数

文字のグリフ輪郭やビットマップを取得する。

DLLGDI32.dll文字セットANSI (-A)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// GDI32.dll  (ANSI / -A)
#include <windows.h>

DWORD GetGlyphOutlineA(
    HDC hdc,
    DWORD uChar,
    GET_GLYPH_OUTLINE_FORMAT fuFormat,
    GLYPHMETRICS* lpgm,
    DWORD cjBuffer,
    void* pvBuffer,   // optional
    const MAT2* lpmat2
);

パラメーター

名前

型

方向

説明

hdc

HDC

デバイスコンテキストへのハンドル。

uChar

DWORD

データを取得する対象の文字。

fuFormat

GET_GLYPH_OUTLINE_FORMAT

関数が取得するデータの形式。このパラメーターには、次のいずれかの値を指定できます。

値	意味
GGO_BEZIER	曲線データを(2 次スプライン形式ではなく)3 次ベジェスプラインとして取得します。
GGO_BITMAP	グリフのビットマップを取得します。メモリの割り当てについては、後述の「解説」セクションを参照してください。
GGO_GLYPH_INDEX	uChar パラメーターが文字コードではなく TrueType グリフインデックスであることを示します。グリフインデックスに関する追加の解説については、ExtTextOut 関数を参照してください。
GGO_GRAY2_BITMAP	5 段階のグレースケールを含むグリフビットマップを取得します。
GGO_GRAY4_BITMAP	17 段階のグレースケールを含むグリフビットマップを取得します。
GGO_GRAY8_BITMAP	65 段階のグレースケールを含むグリフビットマップを取得します。
GGO_METRICS	lpgm で指定された GLYPHMETRICS 構造体のみを取得します。lpvBuffer は無視されます。この値は、失敗時の関数の戻り値の意味に影響します。「戻り値」セクションを参照してください。
GGO_NATIVE	曲線データポイントをラスタライザーのネイティブ形式で取得し、フォントのデザイン単位を使用します。
GGO_UNHINTED	ヒンティングが適用されていないアウトラインのみを返します。このフラグは GGO_BEZIER および GGO_NATIVE と組み合わせた場合にのみ機能します。

GGO_GRAYn_BITMAP の各値については、関数は n^2+1(n の 2 乗に 1 を加えた値)段階のグレースケールを含むグリフビットマップを取得することに注意してください。

lpgm

GLYPHMETRICS*

out

文字セル内でのグリフの配置を記述する GLYPHMETRICS 構造体へのポインター。

cjBuffer

DWORD

関数がアウトライン文字に関する情報をコピーするバッファー(*lpvBuffer)のサイズ(バイト単位)。この値が 0 の場合、関数は必要なバッファーサイズを返します。

pvBuffer

void*

outoptional

アウトライン文字に関する情報を受け取るバッファーへのポインター。この値が NULL の場合、関数は必要なバッファーサイズを返します。

lpmat2

MAT2*

文字の変換マトリックスを指定する MAT2 構造体へのポインター。

戻り値の型: DWORD

公式ドキュメント

GetGlyphOutline 関数は、指定されたデバイスコンテキストに選択されている TrueType フォント内の文字について、アウトラインまたはビットマップを取得します。(ANSI)

戻り値

GGO_BITMAP、GGO_GRAY2_BITMAP、GGO_GRAY4_BITMAP、GGO_GRAY8_BITMAP、または GGO_NATIVE が指定され、関数が成功した場合、戻り値は 0 より大きくなります。それ以外の場合、戻り値は GDI_ERROR です。これらのフラグのいずれかが指定され、バッファーサイズまたはアドレスが 0 の場合、戻り値は必要なバッファーサイズ(バイト単位)を表します。

GGO_METRICS が指定され、関数が失敗した場合、戻り値は GDI_ERROR です。

解説(Remarks)

GetGlyphOutline 関数が返すグリフアウトラインは、グリッドフィットされたグリフのものです。(グリッドフィットされたグリフとは、そのビットマップ画像が元のグリフのデザインにできるだけ近くなるように変更されたグリフです。)変更されていないグリフアウトラインが必要なアプリケーションは、フォントの em 単位に等しいサイズのフォントについて、文字のグリフアウトラインを要求できます。フォントの em 単位の値は、OUTLINETEXTMETRIC 構造体の otmEMSquare メンバーに格納されています。

GGO_BITMAP が指定された場合に GetGlyphOutline が返すグリフビットマップは、DWORD 境界に整列した、行指向のモノクロビットマップです。GGO_GRAY2_BITMAP が指定された場合、返されるビットマップは、値が 0 から 4 の範囲のバイトからなる DWORD 境界に整列した行指向の配列です。GGO_GRAY4_BITMAP が指定された場合、返されるビットマップは、値が 0 から 16 の範囲のバイトからなる DWORD 境界に整列した行指向の配列です。GGO_GRAY8_BITMAP が指定された場合、返されるビットマップは、値が 0 から 64 の範囲のバイトからなる DWORD 境界に整列した行指向の配列です。

GGO_NATIVE が指定された場合に GetGlyphOutline が返すネイティブバッファーは、グリフアウトラインです。グリフアウトラインは、TTPOLYGONHEADER 構造体とそれに続く 1 つ以上の曲線で定義される 1 つ以上の輪郭の連なりとして返されます。輪郭内の各曲線は、TTPOLYCURVE 構造体とそれに続く複数の POINTFX データポイントによって定義されます。POINTFX ポイントは相対的な移動ではなく、絶対位置です。輪郭の開始点は、TTPOLYGONHEADER 構造体の pfxStart メンバーによって与えられます。各曲線の開始点は、前の曲線の最後の点、または輪郭の開始点です。曲線内のデータポイント数は、TTPOLYCURVE 構造体の cpfx メンバーに格納されます。バッファー内の各輪郭のサイズ(バイト単位)は、TTPOLYGONHEADER 構造体の cb メンバーに格納されます。追加の曲線定義は先行する曲線に続いてバッファーに詰め込まれ、追加の輪郭は先行する輪郭に続いてバッファーに詰め込まれます。バッファーには、GetGlyphOutline が返すバッファーに収まるだけの輪郭が含まれます。

GLYPHMETRICS 構造体は、文字セルの幅と、文字セル内でのグリフの位置を指定します。文字セルの原点は、フォントのベースライン上、セルの左側に位置します。グリフ原点の位置は、文字セル原点を基準とする相対位置です。文字セルの高さ、ベースライン、およびフォント全体に共通するその他のメトリックは、OUTLINETEXTMETRIC 構造体によって与えられます。

アプリケーションは、lpMatrix パラメーターに 2 行 2 列の変換マトリックスを指定することで、ビットマップ形式またはネイティブ形式で取得される文字を変更できます。たとえば、行列乗算を使用して、せん断、回転、拡大縮小、またはこれら 3 つの任意の組み合わせによってグリフを変更できます。

グリフアウトラインに関する追加情報は、TrueType および OpenType の技術仕様に記載されています。

メモ

wingdi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして GetGlyphOutline を定義します。エンコーディング非依存のエイリアスの使用を、エンコーディング非依存でないコードと混在させると、コンパイルエラーや実行時エラーを引き起こす不一致につながる可能性があります。詳細については、関数プロトタイプの規約を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// GDI32.dll  (ANSI / -A)
#include <windows.h>

DWORD GetGlyphOutlineA(
    HDC hdc,
    DWORD uChar,
    GET_GLYPH_OUTLINE_FORMAT fuFormat,
    GLYPHMETRICS* lpgm,
    DWORD cjBuffer,
    void* pvBuffer,   // optional
    const MAT2* lpmat2
);

[DllImport("GDI32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint GetGlyphOutlineA(
    IntPtr hdc,   // HDC
    uint uChar,   // DWORD
    uint fuFormat,   // GET_GLYPH_OUTLINE_FORMAT
    IntPtr lpgm,   // GLYPHMETRICS* out
    uint cjBuffer,   // DWORD
    IntPtr pvBuffer,   // void* optional, out
    IntPtr lpmat2   // MAT2*
);

<DllImport("GDI32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function GetGlyphOutlineA(
    hdc As IntPtr,   ' HDC
    uChar As UInteger,   ' DWORD
    fuFormat As UInteger,   ' GET_GLYPH_OUTLINE_FORMAT
    lpgm As IntPtr,   ' GLYPHMETRICS* out
    cjBuffer As UInteger,   ' DWORD
    pvBuffer As IntPtr,   ' void* optional, out
    lpmat2 As IntPtr   ' MAT2*
) As UInteger
End Function

' hdc : HDC
' uChar : DWORD
' fuFormat : GET_GLYPH_OUTLINE_FORMAT
' lpgm : GLYPHMETRICS* out
' cjBuffer : DWORD
' pvBuffer : void* optional, out
' lpmat2 : MAT2*
Declare PtrSafe Function GetGlyphOutlineA Lib "gdi32" ( _
    ByVal hdc As LongPtr, _
    ByVal uChar As Long, _
    ByVal fuFormat As Long, _
    ByVal lpgm As LongPtr, _
    ByVal cjBuffer As Long, _
    ByVal pvBuffer As LongPtr, _
    ByVal lpmat2 As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetGlyphOutlineA = ctypes.windll.gdi32.GetGlyphOutlineA
GetGlyphOutlineA.restype = wintypes.DWORD
GetGlyphOutlineA.argtypes = [
    wintypes.HANDLE,  # hdc : HDC
    wintypes.DWORD,  # uChar : DWORD
    wintypes.DWORD,  # fuFormat : GET_GLYPH_OUTLINE_FORMAT
    ctypes.c_void_p,  # lpgm : GLYPHMETRICS* out
    wintypes.DWORD,  # cjBuffer : DWORD
    ctypes.POINTER(None),  # pvBuffer : void* optional, out
    ctypes.c_void_p,  # lpmat2 : MAT2*
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('GDI32.dll')
GetGlyphOutlineA = Fiddle::Function.new(
  lib['GetGlyphOutlineA'],
  [
    Fiddle::TYPE_VOIDP,  # hdc : HDC
    -Fiddle::TYPE_INT,  # uChar : DWORD
    -Fiddle::TYPE_INT,  # fuFormat : GET_GLYPH_OUTLINE_FORMAT
    Fiddle::TYPE_VOIDP,  # lpgm : GLYPHMETRICS* out
    -Fiddle::TYPE_INT,  # cjBuffer : DWORD
    Fiddle::TYPE_VOIDP,  # pvBuffer : void* optional, out
    Fiddle::TYPE_VOIDP,  # lpmat2 : MAT2*
  ],
  -Fiddle::TYPE_INT)

#[link(name = "gdi32")]
extern "system" {
    fn GetGlyphOutlineA(
        hdc: *mut core::ffi::c_void,  // HDC
        uChar: u32,  // DWORD
        fuFormat: u32,  // GET_GLYPH_OUTLINE_FORMAT
        lpgm: *mut GLYPHMETRICS,  // GLYPHMETRICS* out
        cjBuffer: u32,  // DWORD
        pvBuffer: *mut (),  // void* optional, out
        lpmat2: *const MAT2  // MAT2*
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("GDI32.dll", CharSet = CharSet.Ansi)]
public static extern uint GetGlyphOutlineA(IntPtr hdc, uint uChar, uint fuFormat, IntPtr lpgm, uint cjBuffer, IntPtr pvBuffer, IntPtr lpmat2);
"@
$api = Add-Type -MemberDefinition $sig -Name 'GDI32_GetGlyphOutlineA' -Namespace Win32 -PassThru
# $api::GetGlyphOutlineA(hdc, uChar, fuFormat, lpgm, cjBuffer, pvBuffer, lpmat2)

#uselib "GDI32.dll"
#func global GetGlyphOutlineA "GetGlyphOutlineA" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; GetGlyphOutlineA hdc, uChar, fuFormat, varptr(lpgm), cjBuffer, pvBuffer, varptr(lpmat2)   ; 戻り値は stat
; hdc : HDC -> "sptr"
; uChar : DWORD -> "sptr"
; fuFormat : GET_GLYPH_OUTLINE_FORMAT -> "sptr"
; lpgm : GLYPHMETRICS* out -> "sptr"
; cjBuffer : DWORD -> "sptr"
; pvBuffer : void* optional, out -> "sptr"
; lpmat2 : MAT2* -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "GDI32.dll"
#cfunc global GetGlyphOutlineA "GetGlyphOutlineA" sptr, int, int, var, int, sptr, var
; res = GetGlyphOutlineA(hdc, uChar, fuFormat, lpgm, cjBuffer, pvBuffer, lpmat2)
; hdc : HDC -> "sptr"
; uChar : DWORD -> "int"
; fuFormat : GET_GLYPH_OUTLINE_FORMAT -> "int"
; lpgm : GLYPHMETRICS* out -> "var"
; cjBuffer : DWORD -> "int"
; pvBuffer : void* optional, out -> "sptr"
; lpmat2 : MAT2* -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "GDI32.dll"
#cfunc global GetGlyphOutlineA "GetGlyphOutlineA" sptr, int, int, sptr, int, sptr, sptr
; res = GetGlyphOutlineA(hdc, uChar, fuFormat, varptr(lpgm), cjBuffer, pvBuffer, varptr(lpmat2))
; hdc : HDC -> "sptr"
; uChar : DWORD -> "int"
; fuFormat : GET_GLYPH_OUTLINE_FORMAT -> "int"
; lpgm : GLYPHMETRICS* out -> "sptr"
; cjBuffer : DWORD -> "int"
; pvBuffer : void* optional, out -> "sptr"
; lpmat2 : MAT2* -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。