This chapter describes supplemental libraries provided for using internal system resources, such as power and the pedometer, and shared resources such as internal fonts.
13.1. PTM Library
The PTM library is provided for getting power-related information and using RTC-based alarms.
13.1.1. Initializing and Finalizing
The PTM is initialized and finalized using the nn::ptm::Initialize()
function and the nn::ptm::Finalize()
function.
nn::Result nn::ptm::Initialize(); nn::Result nn::ptm::Finalize();
Neither function returns an error as long as the hardware is not damaged.
13.1.2. Getting Power-Related Information
The following power-related information can be obtained: connection status of the power adapter, charge status of the battery, and the battery level.
nn::ptm::AdapterState nn::ptm::GetAdapterState(); nn::ptm::BatteryChargeState nn::ptm::GetBatteryChargeState(); nn::ptm::BatteryLevel nn::ptm::GetBatteryLevel();
You can get the connection status of the power adapter by calling the nn::ptm::GetAdapterState
function. The following table shows the possible return values.
Values |
Description |
---|---|
|
Power adapter not connected |
|
Power adapter connected |
You can get the battery charge status by calling the nn::ptm::GetBatteryChargeState()
function. The following table shows the possible return values.
Values |
Description |
---|---|
|
Not charging |
|
Charging |
You can get the battery level by calling the nn::ptm::GetBatteryLevel()
function. The following table shows the possible return values.
Values |
Description |
---|---|
|
Battery level is 0% |
|
Battery level is 1% to 5% |
|
Battery level is 6% to 10% |
|
Battery level is 11% to 30% |
|
Battery level is 31% to 60% |
|
Battery level is 61% to 100% |
13.1.3. Alarms Using the RTC
For information about this feature, see 8.5.2. RTC Alarm Feature.
13.2. PL Library
The PL library is provided so that applications can use features and resources built into the 3DS system such as the pedometer and internal (shared) fonts. Although there are no functions for initializing or finalizing the PL library itself, other libraries may need to be initialized in order to use these features and resources.
13.2.1. Pedometer
Pedometer information is recorded in terms of the number of steps for each hour for up to 120 months (approximately 10 years). Because pedometer information is stored in the power-related module, you must initialize the PTM library ahead of time in order to access pedometer information. For information about initializing the PTM library, see 13.1.1. Initializing and Finalizing.
Use the following functions to get pedometer-related information.
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);
The nn::pl::GetPedometerState()
function returns whether the accelerometer is functioning as a pedometer. The accelerometer functions as a pedometer when the power is on and the system is closed. Applications therefore do not need to track whether the accelerometer is functioning as a pedometer because they have usually transitioned into Sleep Mode.
The nn::pl::GetTotalStepCount()
function returns the number of steps accumulated so far.
The nn::pl::GetStepHistoryEntry()
function stores the year and month of recorded step count entries in the nn::pl::PedometerEntry
array specified by pEntry
and returns the number of entries stored as its return value. Allocate enough memory for the array specified by pEntry
so that the maximum number of entries (NUM_MONTHHISTORIES
) can be stored.
The nn::pl::GetSetpHistory()
function stores step count information for each hour for the number of hours specified by numHours
(future direction only) starting from and including the hour specified by start
in the array specified by pStepCounts
. Zero is stored for hours for which there is no step count information.
The nn::pl::GetHistoryAll()
function is used to get all step count information. The step count information obtained is split into header information and data. The order of data corresponds to the order of header information, but header information is not necessarily arranged in order of year and month. The year and month associated with step count information can be confirmed using monthInfo
included in header information. If INVALID_COUNTER
is stored in unusedCounter
for an entry, it indicates that the data is invalid and no step count data has been recorded for that entry.
CTR-SDK includes the PedometerChanger development tool, which lets you view and manipulate the pedometer information.
13.2.2. Internal Fonts
Internal fonts are provided as shared resources that can be accessed by applications. The type of internal fonts loaded as standard differs depending on the region set for the system.
The types of internal fonts that can be used are defined as shown below by the nn::pl::SharedFontType
enumerator type.
Values |
Description |
---|---|
|
European fonts. Standard for the Japanese, European, and United States regions. |
|
Chinese fonts. Standard for the Chinese region. |
|
Korean fonts. Standard for the Korean region. |
|
Taiwanese fonts. Standard for the Taiwanese region. |
13.2.2.1. Loading Internal Fonts
Internal fonts are loaded using the nn::pl::InitializeSharedFont()
function. Although fonts for all regions are built into systems for any region, the InitializeSharedFont()
function only loads those fonts associated with the system region.
nn::Result nn::pl::InitializeSharedFont(); nn::pl::SharedFontLoadState nn::pl::GetSharedFontLoadState();
Calling the nn::pl::InitializeSharedFont()
function starts loading internal fonts. However, loading of internal fonts may not yet be complete when the function finishes executing. The return value (nn::pl::SharedFontLoadState
) of the nn::pl::GetSharedFontLoadState()
function can be used to verify that fonts have finished loading.
Values |
Description |
---|---|
|
Load not started. |
|
Loading. |
|
Load complete. |
|
Load failed. |
You can get the start address, size, and font type of loaded font data using the nn::pl::GetSharedFontAddress
, nn::pl::GetSharedFontSize
, and nn::pl::GetSharedFontType()
functions, respectively.
void* nn::pl::GetSharedFontAddress(); size_t nn::pl::GetSharedFontSize(); nn::pl::SharedFontType nn::pl::GetSharedFontType();
If you want to display characters only included in the internal font of a region other than the system region to, for example, display messages sent from a system of another region, you must mount the internal font archive using the nn::pl::MountSharedFont()
function and have the application load the corresponding internal font.
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
specifies the archive name of the font archive to be mounted.
sharedFontType
specifies the type of internal font to be mounted. The files loaded differ depending on the type of internal font specified here. If the specified font does not exist, nn::pl::ResultSharedFontNotFound
is returned as the return value.
Internal Font Type |
Filename |
---|---|
|
|
|
|
|
|
|
|
Font files are compressed in LZ77 format and should be decompressed using the CX library before using them as fonts.
Specify the number of files and directories that can be opened simultaneously in maxFile
and maxDirectory
, respectively. Pass the working memory and its size to workingMemory
and workingMemorySize
. Use the nn::pl::GetSharedFontRequiredMemorySize()
function to get the size of the working memory required.
Unmount the archive using the nn::pl::UnmountSharedFont()
function after font files have finished loading.
13.2.2.2. Using Font Data
The same format as BCFNT files converted using ctr_FontConverter
is used for internal font data. The nn::font::ResFont
class of the FONT library must be used to display internal fonts.
For information about how to display fonts using the FONT library, see the API Reference and sample demos.
13.2.3. Play Coins
Play Coins accumulate as the user walks around with their system. You are free to make use of these accumulated Play Coins. For example, users might exchange Play Coins for bonus items in your application.
To use Play Coins, you must include the header file nn/pl/CTR/pl_GameCoin.h
and add the library file libnn_plCoin
.
CTR-SDK includes a development tool (PlayCoinSetter) for setting the number of Play Coins a system has.
13.2.3.1. Initialization and Finalization
The initialization and finalization of the library are performed by calling the nn::pl::InitializeGameCoin()
and nn::pl::FinalizeGameCoin()
functions.
void nn::pl::InitializeGameCoin(); void nn::pl::FinalizeGameCoin();
Before initializing the Play Coin library, you must initialize the FS and PTM libraries. Because there is no support for nested initialization calls, even if you call the initialization function multiple times, calling the nn::pl::FinalizeGameCoin()
function once will finalize use of the library.
13.2.3.2. Getting the Number of Play Coins Held
You can get the number of Play Coins held by the system with the nn::pl::GetGameCoinCount()
function.
nn::Result nn::pl::GetGameCoinCount(u16* pCount);
The currently held number of Play Coins is stored in pCount
.
This function has a high load and entails a write to system NAND memory. Other than when starting the application, call it only when there is a possibility that the number of Play Coins might have increased or decreased, such as when recovering from Sleep Mode, the HOME Menu, or a library applet.
When this function returns nn::pl::ResultGameCoinDataReset
, it indicates that the Play Coins have been reset due to corrupt data or some other reason, but it is handled as a success (meaning that the IsSuccess()
function returns true
). When informing the user that the Play Coins have been reset, check whether this value has been returned.
13.2.3.3. Spending Play Coins
Play Coins are spent with the nn::pl::UseGameCoin()
function.
nn::Result nn::pl::UseGameCoin(u16* pCount, u16 useCount);
When the process is successful, the number of Play Coins after spending is stored in pCount
. When the process fails, an undefined value is stored there.
Specify the number of Play Coins to spend in useCount
. When the number specified is more than the number held, no Play Coins are spent, and nn::pl::ResultLackOfGameCoin
is returned to indicate that there were not enough Play Coins.
This function’s load is high and it entails a write to system NAND memory.