13. 補助ライブラリ

この章では、電源や歩数計などの本体内蔵機能や、内蔵フォントなどの共有リソースを利用するための、補助的なライブラリについて説明します。

13.1. PTM ライブラリ

PTM ライブラリは、電源に関する情報の取得と RTC を利用したアラームを使用するためのライブラリです。

13.1.1. 初期化と終了

PTM ライブラリの初期化と終了は、nn::ptm::Initialize()nn::ptm::Finalize() を呼び出して行います。

コード 13-1. PTM ライブラリの初期化と終了
nn::Result nn::ptm::Initialize();
nn::Result nn::ptm::Finalize();

どちらの関数も、ハードウェアが故障しているなどの状況でない限り、エラーを返すことはありません。

13.1.2. 電源に関する情報の取得

電源に関する情報として取得することができるのは、電源アダプタの接続状態、バッテリーの充電状態、バッテリーの残量レベルです。

コード 13-2. 電源に関する情報の取得
nn::ptm::AdapterState       nn::ptm::GetAdapterState();
nn::ptm::BatteryChargeState nn::ptm::GetBatteryChargeState();
nn::ptm::BatteryLevel       nn::ptm::GetBatteryLevel();

nn::ptm::GetAdapterState() を呼び出すことで、電源アダプタの接続状態を取得することができます。返り値には、以下の値が返されます。

表 13-1. nn::ptm::AdapterState 列挙子

説明

ADAPTERSTATE_NOCONNECTED

電源アダプタは接続されていません。

ADAPTERSTATE_CONNECTED

電源アダプタが接続されています。

nn::ptm::GetBatteryChargeState() を呼び出すことで、バッテリーの充電状態を取得することができます。返り値には、以下の値が返されます。

表 13-2. nn::ptm::BatteryChargeState 列挙子

説明

BATTERYCHARGESTATE_NOCHARGING

充電中ではありません。

BATTERYCHARGESTATE_CHARGING

充電中です。

nn::ptm::GetBatteryLevel() を呼び出すことで、バッテリーの残量をレベルで取得することができます。返り値には、以下の値が返されます。

表 13-3. nn::ptm::BatteryLevel 列挙子

説明

BATTERYLEVEL_0BATTERYLEVEL_MIN

バッテリーの残量は 0 % です。

BATTERYLEVEL_1

バッテリーの残量は 1 % ~ 5 % です。

BATTERYLEVEL_2

バッテリーの残量は 6 % ~ 10 % です。

BATTERYLEVEL_3

バッテリーの残量は 11 % ~ 30 % です。

BATTERYLEVEL_4

バッテリーの残量は 31 % ~ 60 % です。

BATTERYLEVEL_5BATTERYLEVEL_MAX

バッテリーの残量は 61 % ~ 100 % です。

13.1.3. RTC を利用したアラーム

この機能については、「8.5.2. RTC アラーム機能」を参照してください。

13.2. PL ライブラリ

PL ライブラリは、歩数計や内蔵(共有)フォントのように 3DS 本体に内蔵されている機能やリソースをアプリケーションで利用するためのライブラリです。PL ライブラリ自身には初期化や終了処理のための関数はありませんが、機能やリソースを利用するために、ほかのライブラリの初期化を必要とする場合があります。

13.2.1. 歩数計

歩数計の情報は最大で 120 ヶ月(約 10 年)、1 時間ごとの歩数で記録されています。電源関係のモジュール内に歩数計の情報が記録されているため、歩数計の情報にアクセスするには、事前に PTM ライブラリの初期化を行っておく必要があります。PTM ライブラリの初期化については、「13.1.1. 初期化と終了」を参照してください。

歩数計に関する情報の取得には、以下の関数を使用します。

コード 13-3. 歩数計の情報を取得する関数
bool nn::pl::GetPedometerState();
u32 nn::pl::GetTotalStepCount();
s8 nn::pl::GetStepHistoryEntry(nn::pl::PedometerEntry* pEntry);
void nn::pl::GetStepHistory(u16 pStepCounts[], s32 numHours, 
                            nn::fnd::DateTime start);
nn::Result nn::pl::GetStepHistoryAll(nn::pl::PedometerHistoryHeader& header, 
                                     nn::pl::PedometerHistoryData& data);

nn::pl::GetPedometerState() は、加速度センサーが歩数計として動作しているかどうかを返します。歩数計として動作するのは電源がオンで蓋が閉じられている状態ですので、通常はスリープに移行しているため、アプリケーションが歩数計として動作しているかどうかを気にする必要はありません。

nn::pl::GetTotalStepCount() は、これまでの累計歩数を返します。

nn::pl::GetStepHistoryEntry() は、pEntry で指定された nn::pl::PedometerEntry の配列に歩数の記録されているエントリの年と月を格納し、格納したエントリ数を返り値に返します。pEntry に指定する配列は、エントリ数の最大値(NUM_MONTHHISTORIES)が格納できるサイズで確保してください。

nn::pl::GetSetpHistory() は、start で指定された日時を含み、そこから numHours 時間分(未来方向のみ)の 1 時間ごとの歩数情報を pStepCounts に指定された配列に格納します。歩数情報のない時間には 0 が格納されます。

nn::pl::GetHistoryAll() は、すべての歩数情報を取得するための関数です。歩数情報はヘッダ情報とデータに分けて取得します。ヘッダ情報の順番とデータの順番は対応していますが、ヘッダ情報は必ずしも年月順に並んでいるとは限りません。何年何月の歩数情報であるかは、ヘッダ情報の monthInfo で確認することができます。その際、unusedCounterINVALID_COUNTER が格納されているエントリは、歩数の記録されていない無効データであることを示します。

補足:

CTR-SDK には、歩数情報の閲覧と操作が可能な開発用ツール(PedometerChanger)が付属しています。

13.2.2. 内蔵フォント

アプリケーションからアクセスすることのできる共有リソースとして、内蔵フォントを用意しています。内蔵フォントは本体のリージョンによって、標準でロードされるフォントの種類が異なります。

利用することのできる内蔵フォントの種類は、nn::pl::SharedFontType 列挙子で以下のように定義されています。

表 13-4. nn::pl::SharedFontType 列挙子

説明

SHARED_FONT_TYPE_STD

日米欧フォント。日本、米州、欧州リージョンの標準です。

SHARED_FONT_TYPE_CN

中国フォント。中国リージョンの標準です。

SHARED_FONT_TYPE_KR

韓国フォント。韓国リージョンの標準です。

SHARED_FONT_TYPE_TW

台湾フォント。台湾リージョンの標準です。

13.2.2.1. 内蔵フォントのロード

内蔵フォントのロードは nn::pl::InitializeSharedFont() で行います。どのリージョンの本体でも、すべてのリージョン用のフォントを内蔵していますが、InitializeSharedFont() では本体のリージョンに対応するフォントのみがロードされます。

コード 13-4. 内蔵フォントのロード
nn::Result nn::pl::InitializeSharedFont();
nn::pl::SharedFontLoadState nn::pl::GetSharedFontLoadState();

nn::pl::InitializeSharedFont() の呼び出しで内蔵フォントのロードが開始されますが、関数の実行が完了した時点では、まだ内蔵フォントのロードが完了していない可能性があります。フォントのロードが完了したかどうかは nn::pl::GetSharedFontLoadState() の返り値(nn::pl::SharedFontLoadState)で確認することができます。

表 13-5. nn::pl::SharedFontLoadState 列挙子

説明

SHARED_FONT_LOAD_STATE_NULL

ロードは開始されていません。

SHARED_FONT_LOAD_STATE_LOADING

ロード中です。

SHARED_FONT_LOAD_STATE_LOADED

ロードは完了しています。

SHARED_FONT_LOAD_STATE_FAILED

ロードに失敗しました。

ロードされたフォントデータの先頭アドレスとサイズ、フォントの種類は、nn::pl::GetSharedFontAddress()nn::pl::GetSharedFontSize()nn::pl::GetSharedFontType() で、それぞれ取得することができます。

コード 13-5. ロードされたフォントデータの情報の取得
void*                  nn::pl::GetSharedFontAddress();
size_t                 nn::pl::GetSharedFontSize();
nn::pl::SharedFontType nn::pl::GetSharedFontType();

ほかのリージョンの本体から送られたメッセージを表示するなど、本体のリージョン以外の内蔵フォントにしか含まれていない文字を表示したい場合は、nn::pl::MountSharedFont() で内蔵フォントのアーカイブをマウントし、対応する内蔵フォントのファイルをアプリケーションでロードしなければなりません。

コード 13-6. 内蔵フォントのロード(ほかのリージョン)
nn::Result nn::pl::MountSharedFont(const char* archiveName, 
        nn::pl::SharedFontType sharedFontType, size_t maxFile, 
        size_t maxDirectory, void* workingMemory, size_t workingMemorySize);
nn::Result nn::pl::UnmountSharedFont(const char* archiveName);
nn::Result nn::pl::GetSharedFontRequiredMemorySize(
        s32* pOut, nn::pl::SharedFontType sharedFontType, size_t maxFile, 
        size_t maxDirectory);

archiveName には、フォントのアーカイブをマウントするアーカイブ名を指定します。

sharedFontType には、マウントする内蔵フォントの種類を指定します。内蔵フォントの種類によって、ロードするファイルが異なります。指定されたフォントが存在しない場合は、返り値に nn::pl::ResultSharedFontNotFound が返されます。

表 13-6. 内蔵フォントの種類と対応するファイル名(アーカイブ名に "font" を指定した場合)

内蔵フォントの種類

ファイル名

SHARED_FONT_TYPE_STD

font:/cbf_std.bcfnt.lz

SHARED_FONT_TYPE_CN

font:/cbf_zh-Hans-CN.bcfnt.lz

SHARED_FONT_TYPE_KR

font:/cbf_ko-Hang-KR.bcfnt.lz

SHARED_FONT_TYPE_TW

font:/cbf_zh-Hant-TW.bcfnt.lz

フォントファイルは LZ77 圧縮されていますので、フォントとして使用する前に CX ライブラリで解凍してください。

maxFile maxDirectory には、同時に開くことができるファイルの数とディレクトリの数をそれぞれ指定します。workingMemoryworkingMemorySize には、作業メモリとそのサイズを渡します。なお、必要となる作業メモリのサイズは nn::pl::GetSharedFontRequiredMemorySize() で取得してください。

フォントファイルのロードが完了したあとは、nn::pl::UnmountSharedFont() でアーカイブをアンマウントしてください。

13.2.2.2. フォントデータの使用

内蔵フォントのデータは、ctr_FontConverter で変換された bcfnt ファイルと同じフォーマットです。そのため、内蔵フォントを表示するには、FONT ライブラリの nn::font::ResFont クラスを利用しなければなりません。

FONT ライブラリによるフォントの表示方法については、関数リファレンスやサンプルデモを参照してください。

13.2.3. ゲームコイン

ユーザーが本体を持ち歩いた歩数で貯まるゲームコインを、アプリケーションで特典との交換など、自由に利用することができます。ゲームコインの所持枚数の取得や消費は PL ライブラリを介して行います。

ゲームコインを利用するには、ヘッダファイル(nn/pl/CTR/pl_GameCoin.h)のインクルードと、ライブラリファイル(libnn_plCoin)の追加が必要です。

補足:

CTR-SDK には、ゲームコインの所持枚数を設定する開発用ツール(PlayCoinSetter)が付属しています。

13.2.3.1. 初期化と終了

ライブラリの初期化と終了は nn::pl::InitializeGameCoin()nn::pl::FinalizeGameCoin() の呼び出しで行います。

コード 13-7. ゲームコインライブラリの初期化と終了
void nn::pl::InitializeGameCoin();
void nn::pl::FinalizeGameCoin();

初期化の前に、FS ライブラリと PTM ライブラリを初期化しておく必要があります。多重呼び出しに対応していませんので、初期化関数が複数回呼び出された場合でも、1 回の nn::pl::FinalizeGameCoin() の呼び出しでライブラリの使用を終了します。

13.2.3.2. 所持枚数の取得

所持しているゲームコインの枚数は nn::pl::GetGameCoinCount() で取得することができます。

コード 13-8. 所持しているゲームコインの枚数の取得
nn::Result nn::pl::GetGameCoinCount(u16* pCount);

pCount には、現在所持しているゲームコインの枚数が格納されます。

この関数は負荷が高く、本体 NAND メモリへの書き込みを伴いますので、アプリケーションの起動時以外では、ゲームコインが増減する可能性のある、スリープや HOME メニュー、ライブラリアプレットからの復帰時などでのみ呼び出すようにしてください。

返り値に nn::pl::ResultGameCoinDataReset が返された場合は、データの破損などでゲームコインが初期化されたことを示しますが、成功(IsSuccess()true を返す)として扱われます。ゲームコインが初期化されてしまったことをユーザーに知らせる場合は、この値が返されていないかをチェックしてください。

13.2.3.3. ゲームコインの消費

ゲームコインの消費は nn::pl::UseGameCoin() で行います。

コード 13-9. ゲームコインの消費
nn::Result nn::pl::UseGameCoin(u16* pCount, u16 useCount);

pCount には、処理に成功したときは消費後のゲームコインの枚数が格納されます。処理に失敗したときは不定値が格納されます。

useCount には、消費するゲームコインの枚数を指定します。所持している枚数よりも多くの枚数を指定した場合はゲームコインは消費されず、返り値にゲームコインの不足を示す nn::pl::ResultLackOfGameCoin が返されます。

この関数は負荷が高く、本体 NAND メモリへの書き込みを伴います。