Merge pull request #275 from lhearachel/bg-window

Document bg_window.c

docs/2d_rendering.md

@@ -0,0 +1,196 @@
+# 2D Rendering
+
+This document aims to outline and summarize the functionality of the Nintendo DS's
+2D rendering system and the wrapping APIs around that system as used in Pokemon
+Platinum.
+
+Much of the underlying systems from the Game Boy Advance still applies to the
+DS. Thus, this document will aim to only highlight the differences.
+
+## Backgrounds
+
+Backgrounds are rendered in layers; the SDK provides support for 8 total layers
+evenly split across the Main and Sub screens. For simplicity, this document will
+refer to layers by the indices `0`, `1`, `2`, and `3` to refer to the set of
+layers accessible to each of the displays.
+
+### Tiling
+
+Like its predecessors, the DS makes use of a basic tiling system with access
+to 656 KB of VRAM. This VRAM chunk is split into 9 total banks of varying sizes:
+
+- Four banks of size 128 KB
+- One bank of size 64 KB
+- One bank of size 32 KB
+- Three banks of size 16 KB
+
+Both the 2D and 3D processing engines can access any of these banks, but
+are not permitted to access the same bank concurrently. The 2D processing engine
+will access these banks to render each of the various backgrounds, while the 3D
+processing engine will fetch textures from these banks during rendering.
+
+Some restrictions apply to accessing each of these banks:
+
+1. The ARM7 co-processor can only access two of the four 128 KB banks.
+2. Sprite graphics are not permitted to be stored in this section of VRAM.
+3. The main screen is not permitted to access the third 16 KB bank.
+
+### Background Types
+
+The console's 2D engine can generate various types of backgrounds, each with
+different supported functions. There are, effectively, three groups of these
+types.
+
+#### Character-type Groups
+
+These background types utilize a traditional tiling system, rendering frames by
+mapping them from VRAM to simple indexing buffer.
+
+##### Static Backgrounds
+
+This is the most ordinary background type. It supports screen resolutions up to
+512x512, 256 on-screen colors, and 16 total palettes (of 16 colors each). It
+also supports all the usual effects:
+
+- Horizontal and vertical flipping flags
+- Horizontal and vertical scrolling
+- Mosaic effects
+- Alpha blending
+- Priority rendering (which permits "layering" backgrounds atop one another)
+- Palette fading
+
+The VRAM buffer supports up to 1024 total tiles for each background of this type.
+
+##### Affine Backgrounds
+
+This background type supports screen resolutions up to 1024x1024, as well as the
+usual set of basic affine transformations:
+
+- Translations
+- Rotations
+- Scaling
+- Reflection
+- Shearing
+
+However, to support these transformations, the flipping flags are disabled, and
+the VRAM buffer supports up to 256 tiles rather than 1024.
+
+##### Affine Extended with Static Functions
+
+This background type is an extension of the Affine type; it supports the same
+screen resolutions and set of affine transformations, but restores support for
+flipping flags and 1024 tiles.
+
+#### Bitmap-type Groups
+
+Rather than rendering frames from tiles mapped onto an indexing buffer, types
+in this group treat VRAM as a true bitmap frame buffer.
+
+##### Affine Extended with 256 Colors
+
+Functionally, this type is identical to a Static with Affine background, but
+effects are applied on the full 512x512 bitmap.
+
+##### Affine Extended with Direct Color
+
+This type is similar to the 256 color extension, but the frame buffer now
+supports direct 15-bit color, permitting up to 32,768 total on-screen colors.
+
+##### Large Screen
+
+This type treats a single 128KB chunk of VRAM as a frame-buffer of size 1024x512.
+
+#### 3D Background
+
+Backgrounds of this type (which is the only member of its group) treat the
+rendering result of the 3D graphics engine as a background layer. Thus,
+backgrounds of this type do not support *most* of the previous 2D effects,
+but do retain support for horizontal scrolling and alpha blending. In addition,
+backgrounds of this type support direct 18-bit color, permitting up to 262,144
+total on-screen colors.
+
+### Background Modes
+
+Background types are restricted to various "modes", as controlled by the SDK.
+The SDK supports 7 total modes:
+
+| Mode | Layer 0 Type  | Layer 1 Type | Layer 2 Type    | Layer 3 Type    |
+| ---: | ------------- | ------------ | --------------- | --------------- |
+|    0 | Static / 3D   | Static       | Static          | Static          |
+|    1 | Static / 3D   | Static       | Static          | Affine          |
+|    2 | Static / 3D   | Static       | Affine          | Affine          |
+|    3 | Static / 3D   | Static       | Static          | Affine Extended |
+|    4 | Static / 3D   | Static       | Affine          | Affine Extended |
+|    5 | Static / 3D   | Static       | Affine Extended | Affine Extended |
+|    6 | 3D Background | N/A          | Large Screen    | N/A             |
+
+Each of the displays can be set to its own background mode; this permits, for
+example, having affine transformations apply to the main screen, but showing
+a simple static HUD on the sub screen.
+
+### The Game Freak API
+
+Game Freak built a minimal wrapping API around the SDK's internals, much of
+which is identical to the similar wrapping API built for the Advance generation.
+This wrapping API restricts the available background types to the following:
+
+```c
+enum BgType {
+    BG_TYPE_STATIC = 0,
+    BG_TYPE_AFFINE,
+    BG_TYPE_STATIC_WITH_AFFINE,
+};
+```
+
+Backgrounds can be quickly constructed via a simple template system, which allows
+storing common properties in ROM:
+
+```c
+typedef struct BgTemplate {
+    u32 x;
+    u32 y;
+    u32 bufferSize;
+    u32 baseTile;
+    u8 screenSize;
+    u8 colorMode;
+    u8 screenBase;
+    u8 charBase;
+    u8 bgExtPltt;
+    u8 priority;
+    u8 areaOver;
+    u8 dummy;
+    BOOL mosaic;
+} BgTemplate;
+```
+
+The wrapping API's primary feature is support for scheduling scroll and VRAM
+transfer operations for future bulk transformation. Most background update
+operations provide `Schedule` alternative, which will perform the operation,
+but delay committing the result to VRAM until the next invocation of
+`Bg_RunScheduledUpdates`. To illustrate, consider the following functions:
+
+```c
+void Bg_FillTilemap(BgConfig *bgConfig, u8 bgLayer, u16 fillVal)
+{
+    if (bgConfig->bgs[bgLayer].tilemapBuffer == NULL) {
+        return;
+    }
+
+    MI_CpuFill16(bgConfig->bgs[bgLayer].tilemapBuffer, fillVal, bgConfig->bgs[bgLayer].bufferSize);
+    Bg_CopyTilemapBufferToVRAM(bgConfig, bgLayer);
+}
+
+void Bg_ScheduleFillTilemap(BgConfig *bgConfig, u8 bgLayer, u16 fillVal)
+{
+    if (bgConfig->bgs[bgLayer].tilemapBuffer == NULL) {
+        return;
+    }
+
+    MI_CpuFill16(bgConfig->bgs[bgLayer].tilemapBuffer, fillVal, bgConfig->bgs[bgLayer].bufferSize);
+    Bg_ScheduleTilemapTransfer(bgConfig, bgLayer);
+}
+```
+
+Note that each of these operations perform the same `MI_CpuFill16` operation,
+but the latter invokes `Bg_ScheduleTilemapTransfer`, which flags the background
+layer for VRAM transfer, usually on the next VBlank callback.

docs/index.md

@@ -9,4 +9,5 @@ For more detailed information about the project as a whole, please refer to its
 
 ## Subsystems
 
+- [2D Graphics](2d_rendering.md)
 - [3D Graphics](3d_rendering.md)

include/battle/ov16_0223DF00.h

@@ -12,11 +12,9 @@
 #include "struct_decls/struct_0200C440_decl.h"
 #include "struct_decls/struct_0200C6E4_decl.h"
 #include "struct_decls/struct_0200C704_decl.h"
-#include "struct_decls/struct_02018340_decl.h"
 #include "struct_decls/struct_020797DC_decl.h"
 #include "struct_decls/struct_party_decl.h"
 #include "struct_defs/chatot_cry.h"
-#include "struct_defs/struct_0205AA50.h"
 #include "struct_defs/trainer_data.h"
 
 #include "battle/battle_context.h"
@@ -31,6 +29,7 @@
 #include "overlay012/struct_ov12_0221FCDC_decl.h"
 
 #include "bag.h"
+#include "bg_window.h"
 #include "game_options.h"
 #include "message.h"
 #include "pokemon.h"
@@ -41,7 +40,7 @@
 #define ENEMY_IN_SLOT_RIGHT 0
 #define ENEMY_IN_SLOT_LEFT  2
 
-BGL *BattleSystem_BGL(BattleSystem *param0);
+BgConfig *BattleSystem_BGL(BattleSystem *param0);
 
 /**
  * @brief Get one of the allocated windows for the battle display.

include/battle/ov16_0226871C.h

@@ -3,14 +3,15 @@
 
 #include "struct_decls/battle_system.h"
 #include "struct_decls/struct_02006C24_decl.h"
-#include "struct_decls/struct_02018340_decl.h"
 #include "struct_defs/struct_0209C370.h"
 
 #include "battle/struct_ov16_02268A14_decl.h"
 #include "battle/struct_ov16_0226AC98.h"
 
-void ov16_02268744(BGL *param0);
-void ov16_022687A0(BGL *param0);
+#include "bg_window.h"
+
+void ov16_02268744(BgConfig *param0);
+void ov16_022687A0(BgConfig *param0);
 void *ov16_022687C8(NARC *param0, NARC *param1, BattleSystem *param2, int param3, UnkStruct_0209C370 *param4);
 void ov16_02268A14(UnkStruct_ov16_02268A14 *param0);
 void ov16_02268A88(UnkStruct_ov16_02268A14 *param0);

include/battle/struct_ov16_0225BFFC_t.h

@@ -4,14 +4,14 @@
 #include "struct_decls/cell_actor_data.h"
 #include "struct_decls/sprite_decl.h"
 #include "struct_decls/struct_02006C24_decl.h"
-#include "struct_defs/struct_0205AA50.h"
 
 #include "battle/struct_ov16_0225BFFC_sub1.h"
 #include "battle/struct_ov16_022674C4.h"
 #include "battle/struct_ov16_0226C378.h"
 #include "overlay012/struct_ball_rotation_decl.h"
 #include "overlay012/struct_ov12_02223764.h"
 
+#include "bg_window.h"
 #include "sys_task_manager.h"
 
 #define DATA_BUF_SIZE 256

include/battle/struct_ov16_02264408.h

@@ -4,15 +4,16 @@
 #include "struct_decls/sprite_decl.h"
 #include "struct_decls/struct_02002F38_decl.h"
 #include "struct_decls/struct_0200C6E4_decl.h"
-#include "struct_decls/struct_02018340_decl.h"
 #include "struct_defs/chatot_cry.h"
 
 #include "battle/struct_ov16_0223E0C8.h"
 #include "battle/struct_ov16_02264408_sub1.h"
 
+#include "bg_window.h"
+
 typedef struct {
     SpriteRenderer *unk_00;
-    BGL *unk_04;
+    BgConfig *unk_04;
     PaletteData *unk_08;
     UnkStruct_ov16_0223E0C8 *unk_0C[4];
     u8 unk_1C[4];

include/battle/struct_ov16_022674C4.h

@@ -3,8 +3,8 @@
 
 #include "struct_decls/battle_system.h"
 #include "struct_decls/cell_actor_data.h"
-#include "struct_defs/struct_0205AA50.h"
 
+#include "bg_window.h"
 #include "sys_task_manager.h"
 
 typedef struct {