MGL::Render::Font
Contents
MGL::Render::Font#
概要#
Fontクラスはフォント描画を行うためのラッパークラスです。
具体的な利用方法についてはフォントの利用方法を参照してください。
宣言#
namespace MGL::Render
{
class Font;
}
メンバ情報#
種類 |
名前 |
内容 |
バージョン |
---|---|---|---|
関数 |
1.0.0+ |
||
関数 |
フォントをストレージに追加 |
1.0.0+ |
|
関数 |
フォント生成用テンプレート |
1.0.0+ |
|
関数 |
フォントの削除 |
1.0.0+ |
|
関数 |
このフォントのキーを取得 |
1.0.0+ |
|
関数 |
表示位置の設定 |
1.0.0+ |
|
関数 |
表示位置の取得 |
1.0.0+ |
|
関数 |
スケール値の設定 |
1.0.0+ |
|
関数 |
スケール値の取得 |
1.0.0+ |
|
関数 |
水平方向の配置情報の設定 |
1.0.0+ |
|
関数 |
水平方向の配置情報の取得 |
1.0.0+ |
|
関数 |
マスクカラーの設定 |
1.0.0+ |
|
関数 |
マスクカラーの取得 |
1.0.0+ |
|
関数 |
透過値の設定 |
1.0.0+ |
|
関数 |
透過値の取得 |
1.0.0+ |
|
関数 |
字間と行間の設定 |
1.0.0+ |
|
関数 |
字間と行間の取得 |
1.0.0+ |
|
関数 |
フォントの有効状態を取得 |
1.0.0+ |
|
関数 |
bool型にキャストした際に有効状態を取得 |
1.0.0+ |
|
関数 |
有効状態を否定演算子で取得 |
1.0.0+ |
|
関数 |
文字の表示 |
1.0.0+ |
|
関数 |
文字列をこのフォント用のインデックス文字列に変換 |
1.0.0+ |
|
関数 |
UTF-32文字をこのフォント用のインデックス文字に変換 |
1.1.7+ |
|
関数 |
インデックス文字列の整形 |
1.1.7+ |
|
関数 |
フォント機能の有効状態を取得 |
1.1.5+ |
|
関数 |
指定した書体を保持しているかを取得 |
1.1.5+ |
|
関数 |
フォントの原点タイプを取得 |
1.1.5+ |
|
関数 |
グリフ情報を取得 |
1.1.5+ |
|
関数 |
表示文字数を設定 |
1.1.6+ |
|
関数 |
表示上限数をクリア |
1.1.6+ |
|
関数 |
表示上限数を取得 |
1.1.6+ |
コンストラクタ#
宣言#
namespace MGL::Render
{
class Font
{
public:
// (1) フォントキーを指定して生成
Font(FontKey key) noexcept
// (2) 空のオブジェクトを生成
constexpr Font() noexcept
}
}
引数#
- (1) フォントキーを指定して生成
- MGL::Render::FontKey key
使用するフォントのキー
説明#
フォントキーを指定してオブジェクトを生成します。利用するフォントはあらかじめCreateまたはAddStorageで登録しておく必要があります。
キーに対応するフォントが見つからなかった場合、IsValidまたはoperator bool()の戻り値がfalse
になります。
(2)は無効なオブジェクトを生成します。通常、アプリケーション側からこの方法で生成する必要はありません。
利用例#
// フォントキーをあらかじめ定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
// フォントキーを用いてフォントを初期化
MGL::Render::Font font(kFontKey);
// フォントの有効性をチェック
if (!font)
{
// キーに対応するフォントが登録されていない場合はここに到達
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
AddStorage#
フォントをストレージに追加
宣言#
namespace MGL::Render
{
class Font
{
public:
static Font AddStorage(FontKey key, SharedFontResource resource) noexcept;
}
}
引数#
- MGL::Render::FontKey key
登録するフォントキー
- MGL::Render::SharedFontResource resource
登録するフォントリソース
戻り値#
正常に登録できた場合はそのフォントオブジェクト。失敗した場合は無効なフォントオブジェクト
説明#
フォントキーとフォントリソースを関連付け、フォントストレージへと登録します。具体的な説明はフォントの利用方法のフォントとフォントリソースおよびフォントリソースの登録を参照してください。
登録するフォントリソースのコンストラクタ以外を呼び出す必要がない場合、Createの利用を推奨します。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
// フォントリソース YourFontResource を生成
auto fontResource = MGL::STL::make_shared<YourFontResource>();
// フォントリソースを登録
MGL::Render::Font::AddStorage(kFontKey, fontResource);
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
Create#
フォント生成用テンプレート
宣言#
namespace MGL::Render
{
class Font
{
template <class FontResourceClass, class... Args>
static Font Create(FontKey key, Args... args) noexcept;
}
}
引数#
- FontResourceClass
登録するフォントリソースクラスの型
- MGL::Render::FontKey key
登録するフォントキー
- Args... args
コンストラクタに渡す引数リスト
戻り値#
正常に登録できた場合はそのフォントオブジェクト。失敗した場合は無効なフォントオブジェクト
説明#
テンプレート引数に指定したフォントリソースクラスを生成して登録するためのテンプレート関数です。
基本的な動作はAddStorageと同等になります。初期化にコンストラクタ以外を呼び出す必要がない場合はこちらの利用を推奨します。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
// フォントリソースを生成して追加
auto fontResource = MGL::Render::Font::Create<YourFontResource>(kFontKey);
if (!fontResource)
{
// 失敗している場合はここに到達
}
// コンストラクタに引数を渡す場合(ここでは例としてanyArgs)
auto fontResource = MGL::Render::Font::Create<YourFontResource>(kFontKey, anyArgs);
if (!fontResource)
{
// 失敗している場合はここに到達
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
Remove#
フォントの削除
宣言#
namespace MGL::Render
{
class Font
{
static void Remove(FontKey key) noexcept;
}
}
引数#
- MGL::Render::FontKey key
削除するフォントのキー
説明#
キーに対応するフォントリソースをフォントストレージから削除します。この関数の呼び出し後、キーを経由したフォントリソースの取得は行えなくなります。
具体的な説明はフォントの利用方法のフォントとフォントリソースおよびフォントリソースの登録を参照してください。
キーに対応するフォントリソースが見つからない場合、この関数は何もしません。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
// kFontKeyで登録したフォントリソースを削除
MGL::Render::Font::Remove(kFontKey);
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
GetFontKey#
このフォントのキーを取得
宣言#
namespace MGL::Render
{
class Font
{
constexpr FontKey GetFontKey() const noexcept;
}
}
戻り値#
- MGL::Render::FontKey
フォントが有効であればこのフォントのキー、無効の場合は不定値
説明#
有効なフォントから、そのフォントに関連付けられているフォントキーを取得します。
無効なフォントから取得した場合、戻り値は不定となります。現時点では0
を返しますが、この値はフォントキーとしては無効な値ではなく、MGLは将来に渡ってこの動作を保証しません。フォントの有効性はフォントキーでは判別せず、IsValidを用いてください。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
// フォントの有効性をチェック: これは IsValid() と等価
if (font)
{
// フォントキーを取得して比較
if (font.GetKey() == kFontKey)
{
// フォントが有効であれば常にここに到達する
}
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
SetPosition#
表示位置の設定
宣言#
namespace MGL::Render
{
class Font
{
// (1) MGL::Vector2で指定
constexpr void SetPosition(const Vector2 &position) noexcept;
// (2) 2つの値で指定
constexpr void SetPosition(float x, float y) noexcept
}
}
引数#
- (1) MGL::Vector2で指定
- const MGL::Vector2 &position
設定する位置
- (2) 2つの値で指定
- float x
設定するX座標
- float y
設定するY座標
説明#
フォントの表示位置を設定します。
フォントオブジェクトは内部に表示位置を保持しており、この関数によって値を変更できます。表示位置はPrintの呼び出しによって更新され、例えは表示内容が幅100ピクセルだった場合、表示位置もx方向に100加算されます。現在の表示位置を取得するにはGetPositionを利用します。
表示位置の基準点はフォントリソースによって異なります。多くの場合は左上またはベースラインが起点となりますが、その定義はフォントリソース側の実装に依存します。このフォントの基準点を取得したい場合はGetOriginTypeを使用してください。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(100.0f, 100.0f);
// "HELLO, MGL" を表示
font.Print("HELLO, MGL");
// 表示後に座標は更新されるため、afterPosition は (100, 100)とは異なる値になる。
// 通常、この直後に Print() を呼び出しても文字が自然に繋がる位置に更新される。
auto afterPosition = font.GetPosition();
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.6
(2)を追加
関連#
GetPosition#
表示位置の取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] constexpr const Vector2 &GetPosition() const noexcept;
}
}
戻り値#
- MGL::Vector2
現在の表示位置
説明#
現在の表示位置を取得します。
この関数で取得する値はSetPositionによって変更可能な他、Printの呼び出しによっても更新される可能性があります。
表示位置の詳細についてはSetPositionを参照してください。
利用例#
SetPositionの利用例を参照してください。
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
SetScale#
スケール値の設定
宣言#
namespace MGL::Render
{
class Font
{
// (1) MGL::Vector2で設定
constexpr void SetScale(const Vector2 &scale) noexcept;
// (2) 2つの値でXとYを設定
constexpr void SetScale(float scaleX, float scaleY) noexcept;
// (3) 1つの値でXとYを同時に設定
constexpr void SetScale(float scale) noexcept;
}
}
引数#
- (1) MGL::Vector2で設定
- const MGL::Vector2 &scale
設定するスケール値
- (2) 2つの値でXとYを設定
- float scaleX
横方向のスケール値
- float scaleY
縦方向のスケール値
- (3) 1つの値でXとYを同時に設定
- float scale
横方向と縦方向の両方に設定するスケール値
説明#
フォントに適用するスケール値を設定します。
(1)はスケール値をMGL::Vector2型で指定し、横方向のスケール値をx
に、縦方向のスケール値をy
に設定します。
(2)と(3)ではMGL::Vector2を用いずに各々の値を直接指定します。
スケール値の適用方法はフォントリソースによって異なります。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// スケール値を縦横2倍に設定
// この指定は次の2つと等価
// font.SetScale(2.0f, 2.0f);
// font.SetScale(2.0f);
font.SetScale(MGL::Vector2(2.0f, 2.0f));
// "HELLO, MGL" を表示
font.Print("HELLO, MGL");
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.6
(2)と(3)を追加
関連#
GetScale#
スケール値の取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] constexpr const Vector2 &GetScale() const noexcept
}
}
戻り値#
- MGL::Vector2
現在のスケール値
説明#
現在設定されているスケール値を取得します。スケール値についての詳細はSetScaleを参照してください。
利用例#
SetScaleの利用例を参照してください。
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
SetHorizontalAlignment#
水平方向の配置情報の設定
宣言#
namespace MGL::Render
{
class Font
{
constexpr void SetHorizontalAlignment(Alignment::Horizontal alignment) noexcept;
}
}
引数#
- MGL::Alignment::Horizontal alignment
設定する配置情報
説明#
フォントの水平方向の配置情報を設定します。引数で指定した値に応じて、フォントリソースに対して行単位での配置方法を指示します。
この値を設定しない場合の初期値はMGL::Alignment::Horizontal::Left
(左揃え)です。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// 中央揃えを指定
font.SetHorizontalAlignment(MGL::Alignment::Horizontal::Center);
// "HELLO, MGL" を表示
font.Print("HELLO, MGL");
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
GetHorizontalAlignment#
水平方向の配置情報の取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] constexpr Alignment::Horizontal GetHorizontalAlignment() const noexcept;
}
}
戻り値#
- MGL::Alignment::Horizontal
現在設定されている配置情報
説明#
現在設定されている水平方向の配置情報を取得します。配置情報についての詳細はSetHorizontalAlignmentを参照してください。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// 水平方向の配置情報を取得
auto horizontalAlignment = font.GetHorizontalAlignment();
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
SetMaskColor#
マスクカラーの設定
宣言#
namespace MGL::Render
{
class Font
{
constexpr void SetMaskColor(const Color &color) noexcept;
}
}
引数#
- MGL::Color color
設定するマスクカラー
説明#
フォント描画に適用するマスクカラーを設定します。マスクカラーについてはMGL::Render::DrawOption2D::SetMaskColorを参照してください。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// フォントの赤成分のみを表示
font.SetMaskColor(MGL::Color::kColorRed);
// "HELLO, MGL" を表示
font.Print("HELLO, MGL");
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
GetMaskColor#
マスクカラーの取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] constexpr const Color &GetMaskColor() const noexcept
}
}
戻り値#
- MGL::Color
現在設定されているマスクカラー
説明#
現在設定されているマスクカラーを取得します。マスクカラーについてはMGL::Render::DrawOption2D::SetMaskColorを参照してください。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// マスクカラーを取得
auto maskColor = font.GetMaskColor();
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
SetSamplerType#
サンプラータイプの設定
宣言#
namespace MGL::Render
{
class Font
{
constexpr void SetSamplerType(SamplerType samplerType) noexcept
}
}
引数#
- MGL::Render::SamplerType samplerType
設定するサンプラータイプ
説明#
フォント描画に適用するサンプラータイプを設定します。サンプラータイプについてはMGL::Render::DrawOption2D::SetSamplerTypeを参照してください。
サンプラータイプの初期設定はMGL::Render::SamplerType::Nearest
(最近傍補間)です。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// 線形補間に設定
font.SetSamplerType(MGL::Render::SamplerType::Linear);
// "HELLO, MGL" を表示
font.Print("HELLO, MGL");
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
GetSamplerType#
サンプラータイプの取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] constexpr SamplerType GetSamplerType() const noexcept;
}
}
戻り値#
- MGL::Render::SamplerType
現在設定されているサンプラータイプ
説明#
現在設定されているサンプラータイプを取得します。サンプラータイプについてはMGL::Render::DrawOption2D::SetSamplerTypeを参照してください。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// サンプラータイプを取得
auto samplerType = font.GetSamplerType()
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
SetTransparency#
透過値の設定
宣言#
namespace MGL::Render
{
class Font
{
constexpr void SetTransparency(float transparency) noexcept;
}
}
引数#
- float transparency
設定する透過値
説明#
フォント描画に適用する透過値を設定します。この関数はSetMaskColorで設定するマスクカラーのalpha
成分のみを書き換える関数となります。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// 透過値を0.5に設定
font.SetTransparency(0.5f);
// "HELLO, MGL" を表示
font.Print("HELLO, MGL");
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
GetTransparency#
透過値の取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] constexpr float GetTransparency() const noexcept;
}
}
戻り値#
- float
現在設定されている透過値
説明#
現在設定されている透過値を取得します。透過値はSetMaskColorで設定するマスクカラーのalpha
成分となり、この関数の戻り値はGetMaskColor().alpha
と等価になります。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// マスクカラーを設定
font.SetMaskColor(1.0f, 1.0f, 1.0f, 0.5f);
// 透過値を取得。この場合は0.5が返る
auto transparency = font.GetTransparency();
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
SetMargin#
字間と行間の設定
宣言#
namespace MGL::Render
{
class Font
{
constexpr void SetMargin(const Vector2 &margin) noexcept;
}
}
引数#
- const MGL::Vector2 &margin
設定する字間と行間
説明#
フォント描画に適用する字間と行間を設定します。引数margin
のx
成分で字間を、y
成分で行間をそれぞれ指定します。
パラメータの初期値は字間、行間共に0.0f
です。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// 字間を 5.0 に設定
font.SetMargin(MGL::Vector2(5.0f, 0.0f));
// "HELLO, MGL" を表示
font.Print("HELLO, MGL");
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
GetMargin#
字間と行間の取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] constexpr const Vector2 &GetMargin() const noexcept;
}
}
戻り値#
- const MGL::Vector2 &
現在設定されている字間と行間
説明#
SetMarginで指定した字間と行間を取得します。戻り値のx
成分が字間、y
成分が行間となります。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// 字間と行間を取得
auto marign = font.GetMargin();
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
IsValid#
フォントの有効状態を取得
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] bool IsValid() const noexcept;
}
}
戻り値#
- bool
有効であれば
true
、無効であればfalse
説明#
フォントの有効状態を取得します。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font.IsValid())
{
// 有効なフォントオブジェクトが生成されている場合はここに到達
}
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
operator bool()#
bool型にキャストした際に有効状態を取得
宣言#
namespace MGL::Render
{
class Font
{
explicit constexpr operator bool() const noexcept;
}
}
戻り値#
- bool
有効であれば
true
、無効であればfalse
説明#
フォントオブジェクトをbool型にキャストし、フォントの有効状態を返すためのオペレーターです。変換結果はIsValidの戻り値と等価です。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// 有効なフォントオブジェクトが生成されている場合はここに到達
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
operator!()#
有効状態を否定演算子で取得
宣言#
namespace MGL::Render
{
class Font
{
bool operator!() const noexcept;
}
}
戻り値#
- bool
有効であれば
false
、無効であればtrue
説明#
否定演算子でフォントオブジェクトを取得するためのオペレーターです。このオペレーターの戻り値はIsValidの結果を反転させた値になります。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (!font)
{
// フォントオブジェクトが無効な場合はここに到達
}
バージョン情報#
- MGL 1.0.0
初回リリース
関連#
Print#
文字の表示
宣言#
namespace MGL::Render
{
class Font
{
// (1) UTF-8の文字列を表示
bool Print(
const char *text,
Text::FormatArgs args = Text::FormatArgs()) noexcept;
// (2) UTF-8の文字列を表示(可変長引数)
template <class... Args>
constexpr bool Print(const char *text, const Args&... args) noexcept;
// (3) インデックス文字列を表示
bool Print(
const Text::IndexedCharacter *indexedString,
Text::FormatArgs args = Text::FormatArgs()) noexcept;
// (4) インデックス文字列を表示(可変長引数)
template <class... Args>
constexpr bool Print(
const Text::IndexedCharacter *indexedString,
const Args&... args) noexcept;
}
}
引数#
- (1)、(2) UTF-8の文字列を表示
- const char *text
表示する文字列
- MGL::Text::FormatArgs args
文字列フォーマットの引数
- (3)、(4) インデックス文字列を表示
- const MGL::Text::IndexedCharacter *indexedString
表示する文字列
- MGL::Text::FormatArgs args
文字列フォーマットの引数
戻り値#
- bool
指定した文字列が最後まで表示された場合は
true
、途中で中断された場合はfalse
説明#
このフォントを用いて指定した文字列を画面上に描画します。
引数のtext
またはindexedString
には表示する文字列を指定します。この引数はテキスト整形に対応しており、その引数は第2引数のargs
に指定します。
第1引数に指定する文字列は、UTF-8またはインデックス文字列のどちらかが利用可能です。インデックス文字列はそのフォントリソース専用に符号化された文字列で、より高速に扱える代わりに、他のフォントリソースとの互換性がありません。詳細はフォントリソースの作成(準備中)を参照してください。
(2)と(4)は可変長引数に対応したテンプレート関数です。第2引数以降の引数は、このテンプレート関数によりMGL::Text::FormatArgsのコンストラクタへと渡されて(1)または(3)を実行します。
指定された文字列が最後まで表示された場合、戻り値にtrue
が返ります。SetLimitsで表示上限数を設定し、最後まで表示されなかった場合はfalse
が返ります。また、引数が不正などの理由で描画そのものが行われなかった場合でもfalse
が返ることがあります。
描画方法に関するより具体的な説明はフォントの利用方法の登録したフォントの利用方法を、テキスト整形についてはテキスト整形を参照してください。
利用例#
フォントの利用方法の登録したフォントの利用方法にて利用例を掲載しているため、そちらを参照してください。
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.5
可変長引数に対応したテンプレート関数を追加
- MGL 1.1.6
戻り値を
void
からbool
に変更
関連#
ToIndexedString#
文字列をこのフォント用のインデックス文字列に変換
宣言#
namespace MGL::Render
{
class Font
{
STL::unique_ptr<Text::IndexedCharacter[]> ToIndexedString(
const char *text,
bool enableFormat,
bool enableTag) const noexcept;
}
}
引数#
- const char *text
変換元の文字列(UTF-8)
- bool enableFormat
テキスト整形の有効化フラグ
- bool enableTag
テキストタグの有効化フラグ
戻り値#
- MGL::STL::unique_ptr < MGL::Text::IndexedCharacter []>
変換結果。失敗時には
nullptr
説明#
引数で指定された文字列をインデックス文字列に変換します。
インデックス文字列はフォントリソースが扱いやすいように符号化した文字列です。UTF-8でエンコーディングされた文字列よりも高速に扱える代わりに、他のフォントリソースとの互換性がありません。インデックス文字列についての詳細はフォントリソースの作成(準備中)を参照してください。
変換元の文字列text
はUTF-8エンコーディングである必要があります。
第2引数enableFormat
および第3引数enableTag
にtrue
を指定すると、テキスト整形とタグの解析を行い、その解析結果に対応したインデックス文字へと変換します。これらの動作を無効にしたい場合はfalse
を指定してください。
フォントがインデックス文字に対応していない場合、この機能は利用できません。また、タグの解析をサポートしていない場合は引数enableTag
は無視されます。これらの利用可否の判別はIsEnabledにて行えます。
利用例#
- 変数宣言
// 次のようなメンバ変数をあらかじめ宣言しているとする MGL::STL::unique_ptr<MGL::Text::IndexedCharacter[]> _indexedString;
- 変換例
// フォントキーからフォントオブジェクトを生成 MGL::Render::Font font(kFontKey); // インデックス化に対応しているかチェック if (font.IsEnabled(MGL::Render::FontFeature::IndexedCharacter)) { // インデックス文字列に変換 _indexedString = font.ToIndexedString("Player HP: {}/{}", true, false); }
- 変換したインデックス文字列を利用する例
// フォントキーからフォントオブジェクトを生成 MGL::Render::Font font(kFontKey); // インデックス文字列を使用して描画 font.Print(_indexedString.get(), {60, 100}); // Player HP: 60/100 のように表示される
バージョン情報#
- MGL 1.0.0
初回リリース
- MGL 1.1.2
引数
enableFormat
を追加- MGL 1.1.5
引数
enableTag
を追加
関連#
ToIndexedCharacter#
文字列をこのフォント用のインデックス文字列に変換
宣言#
namespace MGL::Render
{
class Font
{
[[nodiscard]] Text::IndexedCharacter ToIndexedCharacter(
char32_t character,
FontFaceType faceType = FontFaceType::Default) const noexcept;
}
}
引数#
- char32_t character
変換元の文字(UTF-32)
- MGL::Render::FontFaceType faceType
書体の種類。省略時はデフォルトの書体
戻り値#
- MGL::Text::IndexedCharacter
変換結果。失敗時には
MGL::Text::kIndexedCharacterInvalid
説明#
UTF-32文字をそのフォント用のインデックス文字に変換します。フォントがインデックス文字に対応していない場合、および引数に対応した文字を保持していない場合は取得に失敗しMGL::Text::kIndexedCharacterInvalid
を返します。
フォントのインデックス文字の対応可否の判別はIsEnabledで、書体の対応可否の判別はHasFontFace でそれぞれ判別可能です。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
// UTF-32文字「あ」をインデックス文字に変換
auto indexedCharacter = font.ToIndexedCharacter(U'あ');
バージョン情報#
- MGL 1.1.7
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
Format#
インデックス文字列の整形
宣言#
namespace MGL::Render
{
class Font
{
// (1) テキスト整形
STL::vector<Text::IndexedCharacter> Format(const Text::IndexedCharacter *text, const Text::FormatArgs &args) const noexcept
// (2) 可変長引数でテキスト整形
template <class... Args>
STL::vector<Text::IndexedCharacter> Format(const Text::IndexedCharacter *text, const Args&... args) noexcept
}
}
引数#
- /(1) テキスト整形
- const MGL::Text::IndexedCharacter *text
変換元の文字(インデックス文字列)
- MGL::Text::FormatArgs args
文字列フォーマットの引数
- /(2) 可変長引数でテキスト整形
- const MGL::Text::IndexedCharacter *text
変換元の文字(インデックス文字列)
- MGL::Text::FormatArgs args
文字列フォーマットの引数
戻り値#
- MGL::STL::vector< MGL::Text::IndexedCharacter >
整形後の文字列。失敗時には空の配列
説明#
このフォントが持つフォントリソース向けのインデックス文字列を整形します。この関数の整形結果はPrintと同等ですが、表示を行わず文字列として保持する場合に使用します。
インデックス文字列でない通常の文字列を整形する場合はMGL::Text::Formatを使用してください。
フォントリソースがインデックス文字列に対応していない場合は空の配列を返します。
利用例#
MGL::Render::Font font(kFontKey);
if (!font)
{
// UTF-8文字列をインデックス文字列に変換
auto indexedText = font.ToIndexedString("Player HP: {}");
// インデックス文字列を整形
auto formattedText = font.Format(indexedText, 100);
// 整形後の文字列を表示
font.Print(formattedText.data()); // "Player HP: 100" と表示
}
注釈
通常はこのような使い方をする必要はありません。メッセージコンバータとメッセージホルダーを使用する場合など、インデックス化済みの文字列をベースに整形後の文字列を保持したい場合などに使用してください。
バージョン情報#
- MGL 1.1.7
初回リリース
関連#
IsEnabled#
フォント機能の有効状態を取得
宣言#
namespace MGL::Render
{
class Font
{
public:
[[nodiscard]] constexpr bool IsEnabled(FontFeature feature) const noexcept;
};
}
引数#
- MGL::Render::FontFeature feature
チェックするフォント機能
戻り値#
- bool
引数で指定した機能が有効であれば
true
、無効であればfalse
説明#
このフォントが指定した機能に対応しているかを取得します。フォントが引数feature
で指定された機能に対応している場合はtrue
を、対応していない場合はfalse
を返します。
確認可能な機能の一覧はMGL::Render::FontFeatureの説明を参照してください。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
MGL::Render::Font font(kFontKey);
if (font)
{
// フォントがインデックス文字に対応しているかを取得
if (font.IsEnabled(MGL::Render::FontFeature::IndexedCharacter))
{
MGL_TRACE("フォントはインデックス文字に対応している");
}
}
バージョン情報#
- MGL 1.1.5
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
HasFontFace#
指定した書体を保持しているかを取得
宣言#
namespace MGL::Render
{
class Font
{
public:
[[nodiscard]] constexpr bool HasFontFace(FontFaceType faceType) const noexcept;
};
}
引数#
- MGL::Render::FontFaceType faceType
書体の種類
戻り値#
- bool
引数で指定した書体を保持している場合は
true
、保持していない場合はfalse
説明#
フォントが指定した書体を保持しているかを取得します。
MGL::Render::FontFaceType::Default
はそのフォントがデフォルトで扱う書体を表すため、常にtrue
を返します。それ以外の書体はオプションであり、有効な場合のみtrue
を返します。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
MGL::Render::Font font(kFontKey);
if (font)
{
// フォントがボールド体に対応しているかを取得
if (font.HasFontFace(MGL::Render::FontFaceType::Bold))
{
MGL_TRACE("フォントはボールド体の書体を持っている");
}
}
バージョン情報#
- MGL 1.1.5
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
GetOriginType#
フォントの原点タイプを取得
宣言#
namespace MGL::Render
{
class Font
{
public:
[[nodiscard]] constexpr FontOrigin GetOriginType() const noexcept;
};
}
戻り値#
- MGL::Render::FontOrigin
フォントの原点タイプ
説明#
フォントがどの位置を基準に描画を行うかを取得します。SetPositionが実際にどの座標を表すかはこの原点タイプによって変化します。
詳細はMGL::Render::FontOriginの説明を参照してください。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
MGL::Render::Font font(kFontKey);
if (font)
{
switch (font.GetOriginType())
{
case MGL::Render::FontOrigin::TopLeft:
MGL_TRACE("フォントの原点は左上");
break;
case MGL::Render::FontOrigin::BaseLine:
MGL_TRACE("フォントの原点はベースライン");
break;
}
}
バージョン情報#
- MGL 1.1.5
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
GetGlyph#
グリフ情報を取得
宣言#
namespace MGL::Render
{
class Font
{
public:
// (1) UTF-32文字から取得
[[nodiscard]] constexpr const FontGlyph *GetGlyph(
char32_t character,
FontFaceType faceType = FontFaceType::Default) const noexcept
// (2) インデックス文字から取得
[[nodiscard]] constexpr const FontGlyph *GetGlyph(
Text::IndexedCharacter character,
FontFaceType faceType = FontFaceType::Default) const noexcept
};
}
引数#
- (1) UTF-32文字から取得
- char32_t character
取得する文字
- MGL::Render::FontFaceType faceType
取得する書体の指定。未指定の場合は
MGL::Render::FontFaceType::Default
- (2) インデックス文字から取得
- MGL::Text::IndexedCharacter character
取得する文字
- MGL::Render::FontFaceType faceType
取得する書体の指定。未指定の場合は
MGL::Render::FontFaceType::Default
戻り値#
- const MGL::Render::FontGlyph *
グリフ情報のアドレス。見つからない場合は
nullptr
説明#
文字から対応するグリフの情報を取得します。 (1)ではUTF-32文字から、(2)ではインデックス文字からそれぞれ取得します。
フォントによっては引数で与えたパラメータの他に、スケーリングやマスクカラーなどの描画オプションの値を参照して異なるグリフ情報を返すことがあります。これらの挙動はフォントリソースの実装に依存します。
取得に失敗した場合は戻り値としてnullptr
が返ります。
フォントがグリフ情報の取得に対応していない場合、この関数は利用できません。利用可否の判別はIsEnabledにて行えます。
利用例#
// フォントキーの定義
constexpr auto kFontKey = MGL::Render::MakeFontKey("font-name");
MGL::Render::Font font(kFontKey);
if (font)
{
// フォントから'A'のグリフを取得し、スプライトとして描画する例
if (const auto *glyph = font.GetGlyph('A'); glyph != nullptr)
{
MGL::Render::Renderer2D renderer;
renderer.DrawSprite(MGL::Vector2(100.0f, 100.0f), glyph->texture);
}
}
バージョン情報#
- MGL 1.1.5
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与
関連#
SetLimits#
表示文字数を設定
宣言#
namespace MGL::Render
{
class Font
{
public:
constexpr void SetLimits(int32_t limitCount, bool isOnce) noexcept;
};
}
引数#
- int32_t limitCount
表示する文字の上限数
- bool isOnce
直後のPrintにのみ適用するかのフラグ
説明#
Printで表示する文字の上限数を設定します。表示文字数がlimitCount
で指定した値に達した場合、Printはその時点で描画を中断してfalse
を返すようになります。
引数isOnce
にtrue
を指定した場合、一度描画を実行することでその設定は失われ、次以降の描画に影響を与えません。false
を指定した場合は表示した文字数分だけ消費され、余った上限数は次の描画の実行時に持ち越されます。
limitCount
に負数が指定された場合は上限なしとして扱われます。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// 表示上限数3を直後の描画のみに適用する
font.SetLimit(3, true);
// "HELLO, MGL" を表示。上限数が3なので "HEL" までしか表示されない
font.Print("HELLO, MGL");
// もう一度表示。第2引数に true を指定しているため全て表示される。
font.Print("HELLO, MGL");
// 表示上限数15、設定を引き継ぐよう設定する
font.SetLimit(15, false);
// "HELLO, MGL" を表示。10文字すべてが表示され、上限数は5に更新される
if (font.Print("HELLO, MGL"))
{
// すべて表示するためここには到達する
}
// もう一度表示。上限数の残りが5なので "HELLO" まで表示される
if (font.Print("HELLO, MGL"))
{
// 途中で中断されるためここには到達しない
}
}
バージョン情報#
- MGL 1.1.6
初回リリース
関連#
ClearLimits#
表示上限数をクリア
宣言#
namespace MGL::Render
{
class Font
{
public:
constexpr void ClearLimits() noexcept;
};
}
説明#
表示上限数の設定を初期化して全ての文字を表示するよう指定します。この関数はSetLimits(-1)
と等価です。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// 表示上限数15、設定を引き継ぐよう設定する
font.SetLimit(15, false);
// "HELLO, MGL" を表示。10文字すべてが表示され、上限数は5に更新される
font.Print("HELLO, MGL");
// 上限数をクリアして表示。前回の表示文字数に関わらず全て表示される
font.ClearLimits();
font.Print("HELLO, MGL");
}
バージョン情報#
- MGL 1.1.6
初回リリース
関連#
GetLimits#
表示上限数を取得
宣言#
namespace MGL::Render
{
class Font
{
public:
[[nodiscard]] constexpr int32_t GetLimits() noexcept;
};
}
戻り値#
- int32_t
現在の表示上限数。上限なしの場合は負数
説明#
現在設定されている表示上限数を取得します。
利用例#
// フォントキーからフォントオブジェクトを生成
MGL::Render::Font font(kFontKey);
if (font)
{
// (100, 100)の位置に設定
font.SetPosition(MGL::Vector2(100.0f, 100.0f));
// 表示上限数15、設定を引き継ぐよう設定する
font.SetLimit(15, false);
// "HELLO, MGL" を表示。10文字すべてが表示され、上限数は5に更新される
font.Print("HELLO, MGL")
// 残りの上限数を取得。remainCountには5が代入される
auto remainCount = font.GetLimits();
}
バージョン情報#
- MGL 1.1.6
初回リリース
- MGL 1.1.13
引数の戻り値に
[[nodiscard]]
属性を付与