この章では、電源や歩数計などの本体内蔵機能や、内蔵フォントなどの共有リソースを利用するための、補助的なライブラリについて説明します。
13.1. PTM ライブラリ
PTM ライブラリは、電源に関する情報の取得と RTC を利用したアラームを使用するためのライブラリです。
13.1.1. 初期化と終了
PTM ライブラリの初期化と終了は、nn::ptm::Initialize()
と nn::ptm::Finalize()
を呼び出して行います。
nn::Result nn::ptm::Initialize(); nn::Result nn::ptm::Finalize();
どちらの関数も、ハードウェアが故障しているなどの状況でない限り、エラーを返すことはありません。
13.1.2. 電源に関する情報の取得
電源に関する情報として取得することができるのは、電源アダプタの接続状態、バッテリーの充電状態、バッテリーの残量レベルです。
nn::ptm::AdapterState nn::ptm::GetAdapterState(); nn::ptm::BatteryChargeState nn::ptm::GetBatteryChargeState(); nn::ptm::BatteryLevel nn::ptm::GetBatteryLevel();
nn::ptm::GetAdapterState()
を呼び出すことで、電源アダプタの接続状態を取得することができます。返り値には、以下の値が返されます。
値 |
説明 |
---|---|
|
電源アダプタは接続されていません。 |
|
電源アダプタが接続されています。 |
nn::ptm::GetBatteryChargeState()
を呼び出すことで、バッテリーの充電状態を取得することができます。返り値には、以下の値が返されます。
値 |
説明 |
---|---|
|
充電中ではありません。 |
|
充電中です。 |
nn::ptm::GetBatteryLevel()
を呼び出すことで、バッテリーの残量をレベルで取得することができます。返り値には、以下の値が返されます。
値 |
説明 |
---|---|
|
バッテリーの残量は 0 % です。 |
|
バッテリーの残量は 1 % ~ 5 % です。 |
|
バッテリーの残量は 6 % ~ 10 % です。 |
|
バッテリーの残量は 11 % ~ 30 % です。 |
|
バッテリーの残量は 31 % ~ 60 % です。 |
|
バッテリーの残量は 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. 初期化と終了」を参照してください。
歩数計に関する情報の取得には、以下の関数を使用します。
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
で確認することができます。その際、unusedCounter
に INVALID_COUNTER
が格納されているエントリは、歩数の記録されていない無効データであることを示します。
CTR-SDK には、歩数情報の閲覧と操作が可能な開発用ツール(PedometerChanger)が付属しています。
13.2.2. 内蔵フォント
アプリケーションからアクセスすることのできる共有リソースとして、内蔵フォントを用意しています。内蔵フォントは本体のリージョンによって、標準でロードされるフォントの種類が異なります。
利用することのできる内蔵フォントの種類は、nn::pl::SharedFontType
列挙子で以下のように定義されています。
値 |
説明 |
---|---|
|
日米欧フォント。日本、米州、欧州リージョンの標準です。 |
|
中国フォント。中国リージョンの標準です。 |
|
韓国フォント。韓国リージョンの標準です。 |
|
台湾フォント。台湾リージョンの標準です。 |
13.2.2.1. 内蔵フォントのロード
内蔵フォントのロードは nn::pl::InitializeSharedFont()
で行います。どのリージョンの本体でも、すべてのリージョン用のフォントを内蔵していますが、InitializeSharedFont()
では本体のリージョンに対応するフォントのみがロードされます。
nn::Result nn::pl::InitializeSharedFont(); nn::pl::SharedFontLoadState nn::pl::GetSharedFontLoadState();
nn::pl::InitializeSharedFont()
の呼び出しで内蔵フォントのロードが開始されますが、関数の実行が完了した時点では、まだ内蔵フォントのロードが完了していない可能性があります。フォントのロードが完了したかどうかは nn::pl::GetSharedFontLoadState()
の返り値(nn::pl::SharedFontLoadState
)で確認することができます。
値 |
説明 |
---|---|
|
ロードは開始されていません。 |
|
ロード中です。 |
|
ロードは完了しています。 |
|
ロードに失敗しました。 |
ロードされたフォントデータの先頭アドレスとサイズ、フォントの種類は、nn::pl::GetSharedFontAddress()
と nn::pl::GetSharedFontSize()
、nn::pl::GetSharedFontType()
で、それぞれ取得することができます。
void* nn::pl::GetSharedFontAddress(); size_t nn::pl::GetSharedFontSize(); nn::pl::SharedFontType nn::pl::GetSharedFontType();
ほかのリージョンの本体から送られたメッセージを表示するなど、本体のリージョン以外の内蔵フォントにしか含まれていない文字を表示したい場合は、nn::pl::MountSharedFont()
で内蔵フォントのアーカイブをマウントし、対応する内蔵フォントのファイルをアプリケーションでロードしなければなりません。
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
が返されます。
内蔵フォントの種類 |
ファイル名 |
---|---|
|
|
|
|
|
|
|
|
フォントファイルは LZ77 圧縮されていますので、フォントとして使用する前に CX ライブラリで解凍してください。
maxFile
と maxDirectory
には、同時に開くことができるファイルの数とディレクトリの数をそれぞれ指定します。workingMemory
と workingMemorySize
には、作業メモリとそのサイズを渡します。なお、必要となる作業メモリのサイズは 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()
の呼び出しで行います。
void nn::pl::InitializeGameCoin(); void nn::pl::FinalizeGameCoin();
初期化の前に、FS ライブラリと PTM ライブラリを初期化しておく必要があります。多重呼び出しに対応していませんので、初期化関数が複数回呼び出された場合でも、1 回の nn::pl::FinalizeGameCoin()
の呼び出しでライブラリの使用を終了します。
13.2.3.2. 所持枚数の取得
所持しているゲームコインの枚数は nn::pl::GetGameCoinCount()
で取得することができます。
nn::Result nn::pl::GetGameCoinCount(u16* pCount);
pCount
には、現在所持しているゲームコインの枚数が格納されます。
この関数は負荷が高く、本体 NAND メモリへの書き込みを伴いますので、アプリケーションの起動時以外では、ゲームコインが増減する可能性のある、スリープや HOME メニュー、ライブラリアプレットからの復帰時などでのみ呼び出すようにしてください。
返り値に nn::pl::ResultGameCoinDataReset
が返された場合は、データの破損などでゲームコインが初期化されたことを示しますが、成功(IsSuccess()
が true
を返す)として扱われます。ゲームコインが初期化されてしまったことをユーザーに知らせる場合は、この値が返されていないかをチェックしてください。
13.2.3.3. ゲームコインの消費
ゲームコインの消費は nn::pl::UseGameCoin()
で行います。
nn::Result nn::pl::UseGameCoin(u16* pCount, u16 useCount);
pCount
には、処理に成功したときは消費後のゲームコインの枚数が格納されます。処理に失敗したときは不定値が格納されます。
useCount
には、消費するゲームコインの枚数を指定します。所持している枚数よりも多くの枚数を指定した場合はゲームコインは消費されず、返り値にゲームコインの不足を示す nn::pl::ResultLackOfGameCoin
が返されます。
この関数は負荷が高く、本体 NAND メモリへの書き込みを伴います。