Site copyright © 2006-2023 Jennifer Taylor.
Mastodon

libdragon

libdragon is meant to be a one stop library providing low level API for all hardware features of the N64. Currently, it provides basic console support, rudimentary higher level controller functions, a read only filesystem for appending data to the end of a rom and some 2D graphics functionality. It also includes bindings to newlib in order to provide a posix interface to the filesystem for easier code porting. libdragon is currently available here (last update on February 29, 2012). Alternately, you can pull the latest sources from the git repository on github. If you want to be able to compile the mksprite program used for converting png files into libdragon sprites, you need to have libpng installed.

Complete Feature List

  • Interrupt handler, entrypoint and ldscripts for C and C++ included
  • Timer subsystem for high precision event timing
  • Raw audio playback API
  • Controller handling API
  • Controller accessory API (rumble and mempak support)
  • EEPROM read and write support
  • Buffered video output API
  • Software sprite routines
  • Hardware sprite routines
  • Emulated console API
  • Read-only ROM-based filesystem and API
  • Tools to convert a png file to a libdragon sprite
  • Tools to convert a directory to a libdragon filesystem binary

API Documentation

libdragon employs heavy use of doxygen markup to provide a complete API documentation. This can be built using 'make doxygen-api' or you can visit a prebuilt version here (auto-generated from latest github source). Alternatively, if you wish to have the complete internal documentation generated, type 'make doxygen'. The complete documentation is more appropriate for those wishing to contribute to libdragon. If you wish only to link against libdragon for the purpose of creating homebrew, the simpler API reference is all you need.

Detailed Description

The controller handling API provides a way to poll the controllers in real time to fetch button state on all four controllers. Also provided is a managed API that allows controller states to be polled in a game loop and later queried for changes such as keys down, held and up. There are also functions for detecting and identifying inserted accessories. Current support includes rumble detection and operation as well as full mempak support. Mempak support includes raw block read and write functions as well as functions for formatting, adding a note, deleting a note, and reading a note. These functions should create files that are fully compatible with official N64 games.

Sprites created with mksprite are usable with both software and hardware sprite routines. However, due to hardware limitations, larger sprites may not display properly using hardware methods and must be rendered in software. Additionally, support for drawing filled rectangles using hardware is included. The API is set up in such a way that a double or triple buffered mode set using the buffered video API can be shared between the software and hardware routines seamlessly and statelessly.

The read only filesystem has no limit on the number of files present and allows files to be read from the cartridge memory space using libdragon API or posix system calls. An image can be created using the mkdfs tool and appended to the generated executable to produce a final binary suitable for loading on a flashcart or running in an emulator.

Compatibility

Since libdragon is tested on real hardware, it should be fully compatible with any N64. As long as the particular loading method you use presents the N64 with an interface identical to an original cartridge, all features of libdragon should work. Currently it has been tested on a Doctor V64, Neo N64 and a custom cartridge emulator.

Due to the fact that it doesn't use official libraries, libdragon is not compatible with most N64 emulators. This is due to the fact that emulators meant to play commercial games do not emulate the RCP! They look for calls made to libultra and convert those directly to native rendering instructions. The only emulator known to be compatible with libdragon is MESS due to their efforts to properly emulate the system. MESS 0.145 and newer are fully compatible with libdragon.

Examples

All of the examples mentioned below can be found in the examples subdirectory of the libdragon download.

test

A simple video test which renders using software commands. Demonstrates a proper makefile, proper linking, proper use of the buffered video and software sprite routines, and proper use of the filesystem.

dfsdemo

A modplayer that demonstrates proper use of the filesystem and console routines as well as the proper way to play back modules using libdragon and libmikmod. If you are compiling from source, you will want to include your own modules in a filesystem/ directory (you can include subdirectories).

ctest

A simple controller test that demonstrates detecting inserted controllers and accessories as well as reading simple input from the controllers. Also includes a demonstration of how to use the rumble feature and the mempak raw sector feature.

mptest

A simple accessory test that demonstrates proper init/detection routines as well as how to use the rumble support provided. Also allows a mempak to be cloned.

mputest

A unit test written to test the mempak functionality. This was used in conjunction with THPS1 to verify that formatting, adding and deleting notes conformed to official N64 games. Demonstrates the ability to add and remove notes, format a card, and read a note.

vtest

A video test that tests the various modes available for video output under libdragon.

spritemap

A hardware and software sprite drawing exaple. Demonstrates how to set up and use hardware assisted sprites. Demonstrates how to display an oversized sprite using hardware. Demonstrates use of sprite maps to make animated sprites easier in hardware and software.

Changelist

10/02/2010

  • Updated graphics API and mksprite to allow for spritemaps. Old sprites will be incompatible until you convert them!
  • Added new example demonstrating hardware and software sprite usage.
  • Fixes to RDP texture memory usage and scaled sprites.

9/29/2010

  • Added C++ support to toolchain from ChillyWilly.
  • Added timer subsystem code per ChillyWilly's update.
  • Added line drawing function courtesy of ChillyWilly.
  • Added transparent functions in graphics thanks to ChillyWilly.
  • Added two new video modes and fixed interlaced modes courtesy of ChillyWilly.
  • Adding eeprom reading and writing routines from ChillyWilly.
  • Updated audio subsystem to not be a mess from ChillyWilly.
  • Fixed audio frequency off for NTSC/PAL courtesy of ChillyWilly.
  • Fixed sbrk to gracefully fail with no memory instead of crashing thanks to ChillyWilly.
  • Fixed 16-bit endianness issue reported by ChillyWilly.

6/10/2010

  • Added full mempak support to controller accessory API.
  • Added wait functions.
  • Added a draw scaled sprite hardware function.

6/05/2010

  • Added controller accessory API

5/29/2010

  • Fixed bug in build script
  • Integrated bugfixes in mkdfs program.
  • Made DFS init sequence more robust for different cards.

2/10/2010

  • Merged alt_libn64 to remove dependencies.