CTR-SDK API Guide

Overview

This guide provides the following two types of information to allow developers to understand the features provided by the CTR-SDK.

Contents

Library Overview

Library Name Overview
init Handles processing that precedes a program's main function. By providing functions with particular names, applications can add processing that runs before the main function starts.
os Handles threads, mutexes, timers, clocks, and basic memory management.
fnd Defines common classes used by a number of other libraries, such as allocators, dates, and times.
fs Accesses Game Cards, SD Cards, save data, and other memory locations.
ro Controls dynamic modules.
math Defines numeric functions and classes.
nstd The customized version of the standard library function.
util Defines general-purpose classes.
cx Compresses and expands data.
zlib The CTR-SDK ported version of the open-source zlib library.
crypto Handles encryption-related processing.
jpeg Encodes and decodes JPEG and MPO images.
enc Provides conversion back and forth between UTF-16 and UTF-8.
applet Controls the HOME Menu and Sleep Mode.
ptm Gets power status and controls the real-time clock alarms.
pl Handles pedometer step counts and shared fonts.
news Posts messages to Notifications.
cfg Gets the settings stored in System Memory.
dbg Handles debug output and abnormal program termination.
hio Communicates with a Windows PC through USB. This library can be used only for development purposes.
midi Uses UIC-MIDI to communicate with a MIDI interface. This library can be used only for development purposes.
nngx, nn::gx Controls the GPU.
gl Creates command lists. It uses an OpenGL ES-compatible API, but it increases the CPU load.
gd Creates command lists. It is incompatible with OpenGL ES, but it reduces the CPU load.
gr Provides helper functions for creating command lists.
ulcd Generates appropriate camera matrices based on input from the 3D depth slider.
tpl A library for accessing TPL files, which hold texture data.
font A library for rendering characters and strings using font data created by FontConverter.
snd Uses the sound DSP for sound playback.
dsp Controls the sound DSP.
hid Reads input from buttons, the Circle Pad, the Touch Screen, the accelerometer, and the gyro sensor.
camera Controls the cameras.
y2r Converts YUV image data into RGB format.
mic Gets input from the microphone.
uds Handles direct wireless communication between CTR systems.
rdt Establishes reliable communication channels on top of UDS communication channels.
dlp Handles Download Play.
cec Controls StreetPass.
boss Controls SpotPass.
ac Connects to access points.
http Used by NEX.
socket Used by NEX.
ir Performs infrared communication between consoles.
ndm Controls communication-related background processing.
friends Gets information from the friend list. It also controls logging on to online services.
ngc Checks strings for profanity.
ubl Manages the user blacklist.
erreula Controls the applet that displays the EULA error message.
swkbd Controls the software keyboard applet.
phtsel Controls the photo selector applet.
voicesel Controls the voice selector applet.

Index by Feature

Graphics

Screen Display Handled by the gx, gl, gd, and gr libraries.
Stereoscopic Output Use the gx and ulcd libraries.
Fonts Use the font library.
Use FontConverter to create font data for the font library.
Text Rendering → Fonts
Shared Fonts Use the pl library.
Texture Files Use the tpl library.
Use ctr_TexturePackager to create TPL files for the tpl library.
Encoding and Decoding JPEG Images Use the jpeg library.
Encoding and Decoding MPO Images Use the jpeg library.
Encoding and Decoding Stereoscopic Images → Encoding and Decoding MPO Images
Converting from YUV to RGB Use the y2r library.
Brightness Adjustment You cannot change the brightness or get the current brightness value.
Power-Saving Mode You cannot turn power-saving mode on or off, and you cannot get the current mode.

Sound

Sound Playback Use the snd library.
Shutter Sound Play it using nn::camera::CTR::PlayShutterSound.
Microphone Use the mic library to get input audio.
Using the MIDI Interface (UIC-MIDI) This option can be used only for development purposes.
It cannot be used in retail products.
Use the midi library.
Sound Output Mode Use nn::cfg::CTR::GetSoundOutputMode to get the sound output mode.
Headphone Connection Status Use nn::snd::CTR::GetHeadphoneStatus to get the connection status of headphones.
Sound Volume You cannot get a value for this function.

User Input

+Control Pad, A/B/X/Y/L/R Buttons, START Use nn::hid::CTR::PadReader to get input values.
SELECT This option can be used only for development purposes.
It cannot be used in retail products.
Enable debug mode by using the Config tool, and call nn::hid::CTR::EnableSelectButton to get input from nn::hid::CTR::PadReader.
Circle Pad Use nn::hid::CTR::PadReader to get input values.
Circle Pad Pro Use nn::hid::CTR::ExtraPadReader to get input values.
ZL/ZR Buttons Use nn::hid::CTR::ExtraPadReader to get input values.
Analog Stick → Circle Pad
Touch Panel Use nn::hid::CTR::TouchPanelReader to get input values.
Touch Screen → Touch Panel
Accelerometer Use nn::hid::CTR::AccelerometerReader to get input values.
Gyro Sensor Use nn::hid::CTR::GyroscopeReader to get input values.
Pedometer Use the pl library.
Camera Use the camera library to get camera images.
Microphone Use the mic library to get input audio.
Debug Controller This option can be used only for development purposes.
It cannot be used in retail products.
Use nn::hid::CTR::DebugPadReader to get input values.
3D Depth Slider To use this control indirectly, use the ulcd library.
Sound Volume You cannot get a value for this function.
POWER Button You cannot get input directly from the POWER Button.
→ You must handle Application Close instead.
Wireless Switch You cannot get the wireless switch input.
→ However, wireless-disabled mode has an effect during communication.
HOME Button You cannot get input directly from the HOME Button.
→ You must handle switching to the HOME Menu.

Getting Information Other Than User Input

Remaining Battery Power Use nn::ptm::CTR::GetBatteryLevel to get the remaining battery life.
AC Adapter Connection State Use nn::ptm::CTR::GetAdapterState to get the AC adapter connection state.
Charging Status Use nn::ptm::CTR::GetBatteryChargeState to get the charging status.
Getting System Settings Use the cfg library to get some System Settings.
Date and Time Use nn::fnd::DateTime to get the current date and time.
Use nn::cfg::CTR::GetUserTimeOffset to discover whether and how the time has been changed by the user.
Use nn::os::Tick to get CPU cycle counts.
Username Use nn::cfg::CTR::GetUserName to get the user name.
Birthday Use nn::cfg::CTR::GetBirthday to get the birthday.
Area Use nn::cfg::CTR::GetCountry to get the country, and use nn::cfg::CTR::GetSimpleAddress to get the local area.
Headphone Connection Status Use nn::snd::CTR::GetHeadphoneStatus to get the connection status of headphones.
User Information → Username
→ Birthday
→ Area
Language Use nn::cfg::CTR::GetLanguage to get the language.
Region Use nn::cfg::CTR::GetRegion to get the region.
Sound Output Mode Use nn::cfg::CTR::GetSoundOutputMode to get the sound output mode.
Variable RTC Offset Use nn::cfg::CTR::GetUserTimeOffset to get the variable RTC offset.
System-Specific ID Use nn::cfg::CTR::GetTransferableId to get the system-specific ID.
Pedometer Use the pl library.
Notification LED You cannot manipulate the notification LED directly, or get its state.
The following entries describe the illumination and blinking conditions, and provide related information.
  • When a notification is received
    Illuminates when a notification is received from SpotPass. To send a notification from the server and illuminate the LED, register an application-specific task in SpotPass.
  • When a StreetPass communication is received
    Illuminates when StreetPass is engaged.
    You cannot control this option from the application.
  • When a friend comes online
    Illuminates when a Friend comes online.
    You cannot control this option from the application.
  • When the battery level is very low
    Illuminates when the battery level reaches nn::ptm::CTR::BATTERYLEVEL_1.
    You cannot control this option from the application.
3D LED You cannot control or get the state of the 3D LED directly.
The 3D LED illuminates when NN_GX_DISPLAY_MODE_STEREO is specified to nngxSetDisplayMode, as long as display of 3D images is not restricted by Parental Controls.
Power LED You cannot control or get the state of the power LED.
→ Use the remaining battery life instead.
Recharge LED You cannot control or get the state of the recharge LED.
→ Use the charging status instead.
Wireless LED You cannot manipulate the wireless LED or get its state.
The LED illuminates when wireless communication is activated, and blinks during wireless communication.
Getting the Execution Environment Use nn::os::CTR::GetRunningTargetHardware to get the type of hardware on which an application is running.

Communications

StreetPass Use the cec library.
SpotPass Use the boss library.
Direct, Low-Latency Communication Between CTR Systems Use the uds library.
Direct Data Transfers Between CTR Systems Use the rdt library.
Download Play Use the dlp library.
Infrared Communication Use the ir library.
Getting Friend Information Use the friends library.
Friend List → Getting Friend Information
Friend Registration Applications cannot register friends.
NEX → NEX is distributed with the CTR-NEX package, which is separate from the CTR-SDK. Refer to the CTR-NEX package.
Online Matchmaking → NEX
Online Ranking → NEX
Network Data Storage → NEX
Connecting to an Access Point Use the ac library.
Nintendo Zone Use the ac library to automatically connect to a Nintendo Zone just like an ordinary access point.
USB Communication With a Windows PC This option can be used only for development purposes.
It cannot be used in retail products.
Use the hio library.
Posting Messages Applications can post messages directly using nn::news::CTR::user::PostNews.
You can also post messages through SpotPass.
Internet Communication → Connecting to an Access Point
→ SpotPass
→ NEX
Local Communications → Direct, Low-Latency Wireless Communication Between CTR Systems
→ Direct Wireless Data Transfers Between CTR Systems
→ Download Play
→ Infrared Communication
Nintendo 3DS Service User Agreement → EULA
EULA You must accept the EULA before you can use Internet communication, run StreetPass, or get friend information. To accept the EULA, use the System Settings or Config.
An application can use nn::cfg::CTR::IsAgreedEula to find if the user has accepted the EULA.
Wireless LED You cannot manipulate the wireless indicator LED or get its state.
The LED illuminates when wireless communication is activated, and blinks during wireless communication.
Wireless Switch You cannot get the wireless switch input.
→ However, disabling Wi-Fi during communication has an effect.
Disabled If wireless communication is disabled when you initialize a library that uses wireless, you get an error with an error value to indicate that wireless communication is disabled.
If wireless communication is disabled from the wireless switch when wireless communication is in use, the sequence transitions to one for disconnecting a connection by a library.

Calculation

Matrix and Vector Use the math library.
Quaternions Use the math library.
Floating-Point Functions Use the math library.
Integer Functions Use the math library.
Bit Operations Use the math library.
Random Number Generation Normally you can use the math library for generating pseudo-random numbers.
Use the nn::crypto::GenerateRandomBytes function to generate random numbers that are not repeated.
CRC Calculations Use the util library.
SHA Calculations Use the crypto library.
AES Encryption Use the crypto library.
Compression and Decompression Use the cx library or zlib library.
Encoding and Decoding JPEG Images Use the jpeg library.
Encoding and Decoding MPO Images Use the jpeg library.
Encoding and Decoding Stereoscopic Images → Encoding and Decoding MPO Images

Power and Application Controls

POWER Button You cannot get input directly from the POWER Button.
→ You must handle Application Shutdown instead.
HOME Button You cannot get input directly from the HOME Button.
→ You must handle switching to the HOME Menu.
Power Off Applications cannot turn the system off.
Sleep Applications cannot go into Sleep Mode autonomously. Applications go into sleep mode according to instructions from the system.
For more information, see the applet library.
Sleep Mode → Sleep
Application Shutdown Applications cannot exit autonomously.
Applications close according to instructions from the system.
For more information, see the applet library.
Application Reset Use nn::applet::CTR::RestartApplication.
Remaining Battery Power Use nn::ptm::CTR::GetBatteryLevel to get the remaining battery life.
AC Adapter Connection State Use nn::ptm::CTR::GetAdapterState to get the AC adapter connection state.
Charging Status Use nn::ptm::CTR::GetBatteryChargeState to get the charging status.

OS Foundation

Thread Use os::Thread.
Mutex Use the os library.
Ticks Use os::Tick.
Cycle Counts → Ticks
Timers Use os::Timer.
Memory Management Use the os library for basic allocation of memory to your application. You can use the fnd library to build an allocator in allocated memory.
Device Memory → Memory Management
Exception Handling This option can be used only for development purposes.
It cannot be used in retail products.
Register exception handlers with the os library (nn::os::ARM).
Date and Time Use fnd::DateTime to get the current date and time.

Use os::Tick to get CPU cycle counts.
Dynamic Modules Use the ro library.
DLL → Dynamic module

File System

Game Card Use the fs library.
See nn::fs::MountRom.
Save Data Use the fs library.
See nn::fs::MountSaveData.
Expanded Save Data Use the fs library.
See nn::fs::MountExtSaveData.
SD Card This option can be used only for development purposes.
It cannot be used in retail products.
Use the fs library.
For more information, see nn::fs::MountSdmc.

Debugging

Debug Output This option can be used only for development purposes.
It cannot be used in retail products.
Use macros for debug string output.
ASSERT Use the ASSERT Macro.
Lets you set which handler to call with nn::dbg::SetBreakHandler when the assertion fails.
USB Communication With a Windows PC This option can be used only for development purposes.
It cannot be used in retail products.
Use the hio library.
Using the MIDI Interface (UIC-MIDI) This option can be used only for development purposes.
It cannot be used in retail products.
Use the midi library.
Debug Controller This option can be used only for development purposes.
It cannot be used in retail products.
Use nn::hid::CTR::DebugPadReader to get input values.
Exception Handling This option can be used only for development purposes.
It cannot be used in retail products.
Register exception handlers with the os library (nn::os::ARM).
Getting the Execution Environment Use nn::os::CTR::GetRunningTargetHardware to get the type of hardware on which an application is running.
Accessing SD Cards This option can be used only for development purposes.
It cannot be used in retail products.
Use the fs library.
For more information, see nn::fs::MountSdmc.
SELECT This option can be used only for development purposes.
It cannot be used in retail products.
Enable debug mode by using the Config tool, and call nn::hid::CTR::EnableSelectButton to get input from nn::hid::CTR::PadReader.

HOME Menu

Brightness Adjustment You cannot change the brightness or get the current brightness value.
Power-Saving Mode You cannot turn power-saving mode on or off, and you cannot get the current mode.
Banners For information about how to create banners, see the ctr_makebanner reference.
For information about how to add them to your application, see Build Rules or the Guide to Developing a Build System.
Icons For information about how to create icons, see the ctr_makebanner reference.
For information about how to add them to your application, see Build Rules or the CTR Guide to Developing a Build System.
Software Icons → Icons
SpotPass Notifications These notifications are received from SpotPass. To receive notifications sent from the server, register an application-specific task in SpotPass.
StreetPass Notifications This notification indicates that StreetPass has occurred.
You cannot control this option from the application.
Notifications Distributed Directly From Games Applications can use nn::news::CTR::user::PostNews to distribute notifications directly.
Pedometer Use the pl library.
Play Coins → The library used for Play Coins is distributed with the CTR-SDK Applet package, which is separate from the CTR-SDK itself.
Switching to the HOME Menu Use the applet library.

Applets

Error Messages Use the erreula library.
Software Keyboard Use the swkbd library.
Photo Selector Dialog Box Use the phtsel library.
Voice Selector Dialog Box Use the voicesel library.

Built-In Software

Notifications → SpotPass Notifications
→ StreetPass Notifications
→ Notifications Distributed Directly From Games
Software Library → Register Icon information here. No other operations are possible.
Activity Log → Use Icon information here. No other operations are possible.
AR Cards → Use the AR library to recognize AR Cards. It is distributed separately from the CTR-SDK.
Mii Characters → The CTR Face Library allows you to use Mii characters. It is distributed separately from the CTR-SDK.

System Settings

Username Use nn::cfg::CTR::GetUserName to get the user name.
Birthday Use nn::cfg::CTR::GetBirthday to get the birthday.
Area Use nn::cfg::CTR::GetCountry to get the country, and use nn::cfg::CTR::GetSimpleAddress to get the local area.
Language Use nn::cfg::CTR::GetLanguage to get the language.
Sound Output Mode Use nn::cfg::CTR::GetSoundOutputMode to get the sound output mode.
Variable RTC Offset Use nn::cfg::CTR::GetUserTimeOffset to get the variable RTC offset.
Touch Screen Calibration Applications do not need to calibrate the Touch Screen because it is automatically done by the nn::hid::CTR::TouchPanelReader.
External Camera Calibration Applications do not need to calibrate the cameras to take 3D photos because the cameras are calibrated automatically.

Use nn::camera::CTR::GetStereoCameraCalibrationData to get calibration data and nn::camera::CTR::GetStereoCameraCalibrationMatrixEx to generate a calibration matrix from the calibration data.
Circle Pad Calibration Applications do not need to calibrate the Circle Pad because it is automatically done by the nn::hid::CTR::PadReader.
Parental Controls → Parental Controls
Blocked-User Settings Initialization The ubl library clears the registered blocked-user settings.
Configure Internet Connection Used by Connecting to an Access Point.

Parental Controls

Software Rating Based on the rating information set in Icon, applications with a setting greater than the target age are prohibited from running.
This restriction is applied automatically, and prevents the application from being started from the HOME Menu.
It is not possible to get whether this restriction is enabled.
Internet Browser When enabled, this restriction prevents the Internet Browser from starting.
It is not possible to get whether this restriction is enabled.
Nintendo 3DS Shopping Services When enabled, this restriction prevents the user from purchasing paid content.
It is not possible to get whether this restriction is enabled.
Display of 3D Images When enabled, this restriction prevents the system from displaying stereoscopic images. This restriction is applied automatically. It prevents stereoscopic display even if you set nngxSetDisplayMode to NN_GX_DISPLAYMODE_STEREO.
To determine whether this restriction or the 3D depth slider has prohibited stereoscopic images, call nn::gx::CTR::IsStereoVisionAllowed.
Sharing Images, Audio, and Video When enabled, this restriction prevents the sending and receiving of user-generated content (UGC).
This restriction is not applied automatically. Applications must get a value from nn::cfg::CTR::IsRestrictPhotoExchange and then enforce this restriction.
Online Interaction When enabled, this restriction prevents communication through access points. This restriction is applied automatically. When enabled, it causes connection to an AP to fail.
To determine whether this restriction is enabled, use nn::cfg::CTR::IsRestrictP2pInternet.
StreetPass When enabled, this restriction blocks StreetPass.
This restriction is applied automatically. When enabled, writing a message to a StreetPass box fails. It also blocks the StreetPass feature itself.
To determine whether this restriction is enabled, use nn::cfg::CTR::IsRestrictP2pCec.
Registering Friends It is prohibited to register friends when this restriction is enabled.

To determine whether this restriction is enabled, use nn::cfg::CTR::IsRestrictAddFriend.
DS Download Play DS Download Play is prohibited when this restriction is enabled.
It is not possible to get whether this restriction is enabled.

Revision History

2012/06/22
Added the item about the ASSERT macro.
2011/12/12
Updated information.
2011/07/19
Initial version.

CONFIDENTIAL