This document explains basic information and programming procedures necessary to use 3DS graphics features. 3D graphics features for 3DS are based on OpenGL ES 1.1. To read this document, you must have an understanding of OpenGL in addition to matrix and vector math.
Even though the 3DS system supports the use of OpenGL, for performance reasons, it is often advisable to avoid calling GL functions when you frequently employ 3D graphics features. Instead, write directly to PICA registers using 3D commands and command caches, as described in the 3DS Programming Manual: Advanced Graphics. Please review the CTR Programming Manual: Advanced Graphics, which explains many other features, after you read this document.
Four libraries are provided for drawing graphics: GL, GD, GR, and the collection of graphics libraries included in NintendoWare for CTR (NW4C), distributed by Nintendo.
GL is a basic library that provides functions conforming to OpenGL ES specifications and a rich variety of features, including error handling and state delta management. Accordingly, this library places a heavy processing load on the system. We do not recommend using the GL library when high performance is required.
GD is a lighter-weight library than GL. Although it is not compatible with the GL library, it has equivalent features and provides an easy-to-use API. The GD library requires a certain amount of CPU cycles for internal processing.
GR is a library intended to support the direct creation of 3D commands. Although this library executes the fastest, its use requires in-depth knowledge of how registers are set, meaning that error handling is the responsibility of the developer.
NW4C provides libraries and source code files that use command cache-related features, so be sure to look into the possible use of NW4C. Although NW4C has been implemented to take fullest advantage of optimized performance when used without modification, developers who want to create customized processing can use the GR and GD libraries in combination with NW4C.
There are alignment and size restrictions on the memory passed from the application to the graphics library. Within the programming manual you will find numerical references to the alignment and size restrictions, but they are defined by constants. For more information about the defined constants, see the API reference.
1.1. Document Structure
2. GPU provides an overview of the GPU built into the 3DS system, in addition to a brief summary of its features. This chapter also explains the order in which graphics are processed. Read this chapter to get a grasp of what you can render using 3DS graphics, in addition to an overall picture of graphics processing.
3. LCD explains the relationship between the GX library and the LCD screens built into the 3DS system. Read this chapter to understand the close connection between the GX library and the images displayed on the LCDs.
4. Command Lists explains command lists, which are required to execute 3D graphics commands.
5. Shader Programs describes the types of shader programs and explains how to use them.
6. Vertex Buffers explains how to create and use vertex buffers to input batches of vertex data to the vertex shader.
7. Textures describes the types of texture images that can be handled by the 3DS system, and the CTR native format.
8. Vertex Shaders describes input vertex data, and the vertex attributes that are output for use in later-stage processing.
9. Geometry Shaders provides an overview of and explains how to use the shaders provided by the SDK for generating basic geometry, such as points and lines, and for other useful features, such as silhouettes and subdivision.
10. Rasterization describes the processing that immediately precedes per-fragment operations. The 3DS system runs the scissor test at this stage.
11. Texture Processing explains how texture units, combiners, and combiner buffers determine texel colors; how to combine lights with colors; and how to create procedural textures.
12. Reserved Fragment Shaders describes per-fragment operations that can be controlled using reserved uniforms, such as fragment lighting, shadows, fog, and gas rendering.
13. Per-Fragment Operations describes the operations performed on fragments, before they are written to the render buffer. Refer to this chapter for more information about blending, and the alpha test and other tests.
14. Framebuffer Operations describes framebuffer processing and explains how to clear buffers.
15. Miscellaneous summarizes the differences between the CTR graphics libraries and the OpenGL ES specifications.
3DS Programming Manual: Advanced Graphics presents PICA register information, graphics command caching, and sample implementations of lighting models. It also introduces features that require special settings such as stereoscopic display, block mode, early depth tests, and so on.
1.2. Graphics Processing Errors
3D graphics for 3DS are based on OpenGL ES. Behavior follows the same specifications as OpenGL ES if an error occurs during a call to a 3D graphics function.
- The processing of the function is ignored, except when there is a
GL_OUT_OF_MEMORY
error. - You can get error codes with the
glGetError()
function. - Only a single error code is recorded. The error code is not updated until it is read by the
glGetError()
function, even if another error is generated in the meantime.
The following error codes are recorded.
Error Code |
Conditions for Generating an Error |
---|---|
|
An out-of-range value was specified as a |
|
An out-of-range value was specified as a numeric argument (and similar cases). |
|
A function was called when it was prohibited to do so (and similar cases). |
|
There is not enough memory to execute the function. |
1.3. Single-Threaded Model
The 3D graphics library was designed under the assumption that it would be called from a single thread. Operation is not guaranteed when functions are called from multiple threads. Functions must also be called on only one rendering context.