This chapter describes the software configuration of the 3DS system.
4.1. Applications
To switch from one application to another, you must start the second application using the HOME Menu.
4.2. Standard and Extended Applications
The SNAKE hardware offers two operating modes with different CPU performance: standard mode and extended mode. For more information, see 2.5. Operating Modes. CTR is handled as a platform that only supports the standard mode.
Consequently, two application types are available: standard applications that run in standard mode even on SNAKE, and extended applications that run in extended mode on SNAKE.
Application Type | SNAKE | CTR | Comments |
---|---|---|---|
Standard application | Standard mode | Standard mode | Includes applications built with previous SDKs. |
Extended application | Extended mode | Standard mode |
4.2.1. Creating a Standard Application
If you are using the CTR-SDK build system, comment out the following line in the OMakefile if it exists: "DESCRIPTOR = $(CTRSDK_ROOT)/resources/specfiles/ExtApplication.desc"
.
If you are using VSI-CTR (requires VSI-CTR Platform 3.0.0 or later), in Configuration Properties > General, change Create Extended Application to No.
4.2.2. Creating an Extended Application
If you are using the CTR-SDK build system, add the following line to the OMakefile: "DESCRIPTOR = $(CTRSDK_ROOT)/resources/specfiles/ExtApplication.desc"
.
If you are using VSI-CTR (requires VSI-CTR Platform 3.0.0 or later), in Configuration Properties > General, change Create Extended Application to Yes.
4.2.3. Things to Note When Using Extended Mode
The L2 cache is enabled in extended mode. However, the performance of functions such as nngxUpdaterBuffer
might decrease due to the large capacity of the L2 cache.
To avoid this performance drop, variants of some API functions are provided for specific purposes in extended mode. Be sure to use the right function when handling graphics in your application while running in extended mode.
4.2.4. When the Operating Mode Changes
On SNAKE, the operating mode changes when nn::applet::Enable
is called. Consequently, even standard applications run in extended mode from the time the 3DS logo is displayed until control is passed to the application and nn::applet::Enable
is called.
The system always runs in extended mode while the HOME Menu is displayed, regardless of whether an application is running. When a standard application is suspended by the HOME Menu, the system changes from standard mode to extended mode, and then back to standard mode when control returns to the application.
System applets such as Game Notes and Internet Browser also suspend the application and switch the operating mode to extended mode in the same manner as the HOME Menu.
Application Type | Logo Display | nn::applet::Enable | Application | HOME Menu | Library Applet | System Applets |
---|---|---|---|---|---|---|
Extended application | Extended mode | Extended mode | Extended mode | Extended mode | Extended mode | Extended mode |
Standard application | Extended mode | Standard mode | Standard mode | Extended mode | Standard mode | Extended mode |
4.2.5. Changing Application Behavior on SNAKE and CTR
With the addition of SNAKE to the 3DS family, in some cases it may be necessary to modify the behavior of an application depending on the type of hardware it is running on.
An application can determine whether it is running on SNAKE hardware by calling the nn::os::IsRunOnSnake
function. This allows hardware-specific implementations, such as omitting the Circle Pad Pro connection check on SNAKE hardware, which has the equivalent input devices built into the system.
An application created as an extended application can determine whether it is running in extended mode on SNAKE by calling the nn::os::IsRunningAsExtApplication
function. Note, however, that this function has a high execution cost and cannot be called inside nninitStartUp
.
The nn::os::IsRunOnSnake
and nn::os::IsRunningAsExtApplication
functions return the following values for the various combinations of hardware and application type.
Hardware | Application | IsRunOnSnake | IsRunningAsExtApplication |
---|---|---|---|
SNAKE | Extended application | true |
true |
Standard application | true |
false |
|
CTR | Extended application | false |
false |
Standard application | false |
false |
Always use the nn::os::IsRunningAsExtApplication
function to determine whether the application can use the enhanced features in extended mode (such as additional memory and CPU performance). The cache manipulation functions that are added when the L2 cache is enabled, however, can be used even in standard mode.
Use the nn::os::IsRunOnSnake
function to determine whether any other devices with different specifications on SNAKE and CTR can be used.
4.2.6. SNAKE-Only Titles
For applications that only operate on SNAKE, set the SNAKEOnly
item in the BSF file to True
. SNAKE-only titles do not run on CTR, so you do not need to consider operations on CTR.
For more information about BSF files, see the reference manual for the CTR-SDK tool ctr_makebanner
.
4.3. What the SDK Provides
The 3DS SDK includes not only libraries for handling device input such as key presses, but also provides applets and libraries for using features such as the HOME Menu and SpotPass.
4.3.1. Applets
Much like the HOME Menu, applets provide features for specific purposes that applications can use. Using applet features can help reduce the cost of developing applications.
Only applets provided by Nintendo can be used. Developers cannot create their own applets.
4.3.2. Libraries
CTR-SDK includes the libraries needed to use the hardware. Each library has its own namespace derived from the library name and comprises multiple classes and member functions.
Libraries are written mainly in C++, with wrapper functions written in C. For more information about the C-language wrapper functions, see the CTR-SDK API Reference. The following descriptions all use C++ for function names and other code.
Library Name |
Namespace |
Description |
---|---|---|
OS |
|
A collection of classes for memory allocation, mutual exclusion, ticks, alarms, threads, and other operating system-related features. |
RO |
|
Provides DLL features. |
APPLET |
|
Supports starting applets, transitioning the system to sleep when the system is closed, and other functionality. |
FS |
|
Used for accessing files on various media. |
CX |
|
Handles data compression and decompression. |
MATH |
|
A collection of mathematical and numeric functions. |
CRYPTO |
|
Handles encryption. |
FND |
|
A collection of heap, time, and other fundamental classes. |
FONT |
|
Handles character drawing using font data. |
HID |
|
Handles input from the digital buttons, Circle Pad, touch panel, accelerometer, gyro sensor, and debug pad. |
PTM |
|
Controls system power and alarms. |
GX |
|
Handles GPU and LCD control. Uses the |
GD |
|
A lighter-weight version of the 3D graphics rendering functions in the GX library. |
GR |
|
Supports direct generation of 3D graphics commands. |
MIC |
|
Handles automatic microphone sampling. |
CAMERA |
|
Handles image capture using a camera. |
Y2R |
|
Handles conversion from YUV to RGB format using the YUVtoRGB circuit. |
DSP |
|
Allows use of DSP for sound playback |
SND |
|
Handles local sound playback. |
NDM |
|
Controls the daemon carrying out network processes. |
UDS |
|
Handles wireless communications using the wireless communications module. |
RDT |
|
Allows secure data communication using the UDS library. |
CEC |
|
Handles StreetPass [Chance Encounter Communication (CEC)] settings and other features. |
DLP |
|
Supports Nintendo 3DS Download Play. |
AC |
|
Handles automatic connections for infrastructure communication. |
BOSS |
|
Handles download task registration. |
FRIENDS |
|
Supports access to friend information. |
NEWS |
|
Posts notifications. |
EC |
|
For using the EC features. |
IR | nn::ir |
For using infrared communication between systems. |
ULCD |
|
Calculates the left- and right-eye camera matrices used in stereoscopic display. |
JPEG |
|
Handles encoding to and decoding from JPEG format. |
TPL |
|
Handles texture collection TPL files. |
CFG |
|
Gets information handled by System Settings. |
NGC |
|
Used to check for words that are in the profanity list. |
UBL |
|
Manages the blocked-user list.. |
PL |
|
Used for features unique to the 3DS (such as the pedometer). |
UTIL |
|
Utility functions. |
ENC |
|
Handles encoding conversions. |
ERR |
|
Error handling. |
ERREULA |
|
For using the Error/EULA applet. |
SWKBD |
|
For using the software keyboard applet. |
PHTSEL |
|
For using the photo selection applet. |
VOICESEL |
|
For using the sound selection applet. |
EXTRAPAD |
|
For using the Circle Pad Pro calibration applet. |
WEBBRS |
|
For using the Internet browser. |
OLV |
|
For using the Miiverse application and the Post app. |
SOCKET |
|
(Debugging Only) Handles socket communication. |
SSL |
|
(Debugging Only) Handles SSL communication. |
HTTP |
|
(Debugging Only) Handles HTTP communication. |
DBG |
|
Assists in debugging. |
HIO |
|
(Debugging Only) For using Host IO. |
MIDI |
|
(Debugging Only) For using MIDI. |
Library configurations and names may be changed in the future.
4.4. Error Handling
When the 3DS system is updated, the libraries are also updated. As a result, functions could return values that were not defined at the time the application was developed. To handle such cases, you must use the function nn::Result::IsSuccess
or nn::Result::IsFailure
to determine whether a process has succeeded.
Nintendo does not recommend error handling that only uses value matching to determine errors rather than using these functions, because doing so could cause the application to erroneously assume success or failure when an unexpected error occurs.
When errors that differ from the symptoms in the reference occur only on a particular device, you should suspect a problem with that hardware.