SDL-3DS

SDL-3DS
SDL-3DS
General
Author	nop90
Type	Developments
Version	0.9
License	Mixed
Last Updated	2017/07/27
Links
	Download
	Website
	Source

SDL-3DS is a 3DS port of SDL 1.2 - Simple DirectMedia Layer Version 1.2.15.

Installation

Extract the zip archive in your devkitPro/portlibs/3ds folder. These libs depend on other libs: refer to the SDL documentation.

Run make all to build and install:

SDL
SDL_ttf
SDL_mixer
SDL_image
SDL_net
SDL_sound
SDL_gfx

The installation script for SDL_image and SDL_gfx need to be fixed, so the global makefile uses two prebuilt makefiles.

User guide

Video

The video device will be rendered centered on the HW screen (default screen is the TOP one). Five bpp modes supported: 32 (RGBA8), 24 (RGB8), 16 (RGB565), 15 (RGB555_A1), 8 (paletted)

With these video sizes can be used the following options:

SDL_FULLSCREEN - Option stretchs the video device on the HW screen.
SDL_TOPSCR - Select the top screen for rendering the video device (it's the default option, so you don't really need to set this flag).
SDL_BOTTOMSCR - Select the bottom screen for rendering the video device.
SDL_DUALSCR - Draws the upper half of the video device on the top screeen and the lower half on the bottom screen.
SDL_FITWIDTH - Resizes the video device to fit the selected screen width (if SDL_DUALSCR is set, it's resized to 400 pixel width).
SDL_FITHEIGHT - Resizes the video device to fit the screen/screens height.
SDL_CONSOLETOP - Enables console output on the top screen (only if SDL_TOPSCR or SDL_FULLSCREEN are not set).
SDL_CONSOLEBOTTOM - Enables console output on the bottom screen (only if SDL_BOTTOMSCR or SDL_FULLSCREEN are not set).

Note: using the SDL_FULLSCREEN flag is the same of using (SDL_TOPSCR | SDL_BOTTOMSCR).

Events

SDL events handles the interaction with the 3ds home menu in homebrews released in installable format (CIA).
The lib puts the code in the sleep mode when closing the lid and triggers a SDL_QUIT event when closing the app from the 3ds home menu.
Rmember that once the SDL_QUIT event is triggered, the code can't access anymore to the video services or thecode will hung.

Key Iuput

Default key bindings are:

KEY_A      -> SDLK_a
KEY_B      -> SDLK_b
KEY_X      -> SDLK_x
KEY_Y      -> SDLK_y
KEY_L      -> SDLK_l
KEY_R      -> SDLK_r
KEY_ZL     -> SDLK_LSHIFT
KEY_ZR     -> SDLK_RSHIFT
KEY_START  -> SDLK_RETURN
KEY_SELECT -> SDLK_ESCAPE
KEY_RIGHT  -> SDLK_RIGHT
KEY_LEFT   -> SDLK_LEFT
SDLK_UP    -> KEY_UP
KEY_DOWN   -> SDLK_DOWN

There is a custom function to bind one or more N3DS keys to a SDL key value:

void SDL_N3DSKeyBind(unsigned int hidkey, SDLKey key)

Note: circle pad and C-Stick are not mapped to the direction key by default( circle pad is mapped to the default Joystick) but if someone wants to make this mapping he can use the following code:

SDL_N3DSKeyBind(KEY_CPAD_UP|KEY_CSTICK_UP, SDLK_UP);
SDL_N3DSKeyBind(KEY_CPAD_DOWN|KEY_CSTICK_DOWN, SDLK_DOWN);
SDL_N3DSKeyBind(KEY_CPAD_LEFT|KEY_CSTICK_LEFT, SDLK_LEFT);
SDL_N3DSKeyBind(KEY_CPAD_RIGHT|KEY_CSTICK_RIGHT, SDLK_RIGHT);

It's not possible to bind a N3DS key to two or more SDL Key values.

Joystick

Joystick support is enabled.

Mousepointer

Mouse pointer is controlled with the touchpad.
Touching the bottom screen controls the pointer position and trigger a left button click.

Audio

Supported audio format are AUDIO_S8 and AUDIO_S16.
Audio uses the DSP, so to use it with a homebrew compiled as a CIA you need to dump the DSp Firm in the 3ds folder.
Audio thread would have a higher priority than the main thread, but it would give main thread a fixed time to process the audio.
If you are experiencing problems with the audio, try using a larger sample buffer or change the delay time in SDL_n3dsaudio.c

Multithread

Multithread is supported. But please bear in mind that due to the design of 3DS' OS, thread won't evenly share CPU time.
You would have to use SDL_Delay to give other threads CPU time to run.
All threads would be created with a higher priority than the main thread, and they would start running as soon as you create them.

Changelog

v0.9 2007/07/27

Reduced video thread priority to avoid conflicts with ctulib threads, mainly the NDSP handler one.
Fixed a crash callingSDL_SetVideoMode a secont time, caused by not releasing the scene (shader ans Rendertargets) before loading it again with the new video mode.

v0.8 2017/05/29

Fixed bottom screen zoom/positioning in dual screen mode.
Changed code to maintain screen aspect ratio using SDL_FITWIDTH or SDL_FITHEIGHT custom video flags.
Aligned mouse movement area to bottom screen visible part in dual screen mode.

v0.7 2017/04/07

Video code reworked - GPU freezing highly reduced (played severals SDL games for long time on old and new 3ds without freezes).
Fixed SDL_QUIT event triggering on closing the application from Home menu.
Fixed Audio and Video Therads to not acces DSP ang GPU on app pause and app exiting (SDL_QUIT).
Udated to use tatest DevKitPro and ctrulib.
Using latest fix on Citro3d lib ("Next" branch on github) to reduce GPU freezes.
Added SDL_net. Compiling but untested.

v0.6 2017/03/22

Fixed Video Fickering.
Minor tunings.

v0.5 2017/02/17

Fixed Audio, Threads and Timer (by @Wenting).
Fixed Joystick.
Added 8bpp video mode (from @Wenting).
Minor tuning.
Moved lib installation path from portilibs/armv6k to portilibs/3ds (reinslalling please delete the old lib and the include forlder by hand).
Fixed the makefile for compiling the pica shader file.

v0.4 2017/01/30

Respect to Rikku's v0.3 the video device code was completly rewritten using C3D for the final rendering. This means that there is no need to rotate the screen anymore, both top and bottom screens are supported, there are no limits to video sizes (with possibility to HW stretching the video to the 3ds screen size) and there are four available video modes (RGBA8, RGB8, RGB565, RGB5A1).
Note that the internal drawing routines aren't HW acelerated, C3DS is used only for the final blitting from the videobuffer to the HW framebuffer, allowing for HW screen scaling. So do not expect high farmerate using this lib. Maybe I'll add some optimizations to one of the next releases, but this lib is for simplify the developement on the 3ds, if you need performance there are other low level tools available.
At the moment the video part is almost completed, the input part is at 50% and the sound device is under developement (so no sound support yet).

Credits

This port of the SDL 1.2 lib to 3ds was made with the help of several coders of the 3ds scene: Xerpi, Rikku2000, Nop90, Wenting,

The autotools scripts where tuned with the help of WinterMute (maintainer of DevkitPro).

External links