4. Software Configuration

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.

Figure 4-1. Application Switching

Application A Push HOME button HOME Menu Start Application Application B

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.

Table 4-1. Application Types and Operating Modes on Each Platform
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.

Table 4-2. Application Types and Timing of Operating Mode Change
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.

Table 4-3. Return Values for Hardware and Application Combinations
Hardware Application IsRunOnSnake IsRunningAsExtApplication
SNAKE Extended application true true
Standard application true false
CTR Extended application false false
Standard application false false
Warning:

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.

Note:

 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.

Warning:

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.

Table 4-4. Library List

Library Name

Namespace

Description

OS

nn::os

A collection of classes for memory allocation, mutual exclusion, ticks, alarms, threads, and other operating system-related features.

RO

nn::ro

Provides DLL features.

APPLET

nn::applet

Supports starting applets, transitioning the system to sleep when the system is closed, and other functionality.

FS

nn::fs

Used for accessing files on various media.

CX

nn::cx

Handles data compression and decompression.

MATH

nn::math

A collection of mathematical and numeric functions.

CRYPTO

nn::crypto

Handles encryption.

FND

nn::fnd

A collection of heap, time, and other fundamental classes.

FONT

nn::font

Handles character drawing using font data.

HID

nn::hid

Handles input from the digital buttons, Circle Pad, touch panel, accelerometer, gyro sensor, and debug pad.

PTM

nn::ptm

Controls system power and alarms.

GX

nn::gx

Handles GPU and LCD control. Uses the gl and nngx() functions for 3D graphics rendering.

GD

nn::gd

A lighter-weight version of the 3D graphics rendering functions in the GX library.

GR

nn::gr

Supports direct generation of 3D graphics commands.

MIC

nn::mic

Handles automatic microphone sampling.

CAMERA

nn::camera

Handles image capture using a camera.

Y2R

nn::y2r

Handles conversion from YUV to RGB format using the YUVtoRGB circuit.

QTM

nn::qtm

Handles face tracking. Available only on SNAKE.

DSP

nn::dsp

Allows use of DSP for sound playback

SND

nn::snd

Handles local sound playback.

AACDEC

nn::aacdec

Handles AAC data decoding.

AACENC

nn::aacenc

Handles AAC data encoding.

NDM

nn::ndm

Controls the daemon carrying out network processes.

UDS

nn::uds

Handles wireless communications using the wireless communications module.

RDT

nn::rdt

Allows secure data communication using the UDS library.

CEC

nn::cec

Handles StreetPass [Chance Encounter Communication (CEC)] settings and other features.

DLP

nn::dlp

Supports Nintendo 3DS Download Play.

AC

nn::ac

Handles automatic connections for infrastructure communication.

BOSS

nn::boss

Handles download task registration.

FRIENDS

nn::friends

Supports access to friend information.

NEWS

nn::news

Posts notifications.

ACT

nn::act

Gets information registered to the account system and authenticates it.

EC

nn::ec

For using the EC features.

IR nn::ir For using infrared communication between systems.

NFP

nn::nfp

Allows linking between the application and branded character products called amiibo™ figures.

ULCD

nn::ulcd

Calculates the left- and right-eye camera matrices used in stereoscopic display.

JPEG

nn::jpeg

Handles encoding to and decoding from JPEG format.

TPL

nn::tpl

Handles texture collection TPL files.

CFG

nn::cfg

Gets information handled by System Settings.

NGC

nn::ngc

Checks for words that are in the profanity list.

UBL

nn::ubl

Manages the blocked-user list..

PL

nn::pl

Used for features unique to the 3DS (such as the pedometer).

UTIL

nn::util

Utility functions.

ENC

nn::enc

Handles encoding conversions.

ERR

nn::err

Error handling.

ERREULA

nn::erreula

For using the Error/EULA applet.

SWKBD

nn::swkbd

For using the software keyboard applet.

PHTSEL

nn::phtsel

For using the photo selection applet.

VOICESEL

nn::voicesel

For using the sound selection applet.

EXTRAPAD

nn::extrapad

For using the Circle Pad Pro calibration applet.

WEBBRS

nn::webbrs

For using the Internet browser.

OLV

nn::olv

For using the Miiverse application and the Post app.

SOCKET

nn::socket

(Debugging Only) Handles socket communication.

SSL

nn::ssl

(Debugging Only) Handles SSL communication.

HTTP

nn::http

(Debugging Only) Handles HTTP communication.

DBG

nn::dbg

Assists in debugging.

HIO

nn::hio

(Debugging Only) For using Host IO.

MIDI

nn::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 nn::Result::IsSuccess() or nn::Result::IsFailure() function 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.

Note:

When errors that differ from the symptoms in the reference occur only on a particular device, a hardware problem may be occurring.


CONFIDENTIAL