Refactor hello and cppdemo examples, fix cdxa

5 files changed, 403 insertions, 267 deletions

diff --git a/examples/beginner/cppdemo/CMakeLists.txt b/examples/beginner/cppdemo/CMakeLists.txt
deleted file mode 100644
index 11a35ed..0000000
--- a/examples/beginner/cppdemo/CMakeLists.txt
+++ /dev/null
@@ -1,18 +0,0 @@
-# PSn00bSDK example CMake script
-# (C) 2021 spicyjpeg - MPL licensed
-
-cmake_minimum_required(VERSION 3.21)
-
-project(
-	cppdemo
-	LANGUAGES    CXX
-	VERSION      1.0.0
-	DESCRIPTION  "PSn00bSDK basic C++ example"
-	HOMEPAGE_URL "http://lameguy64.net/?page=psn00bsdk"
-)
-
-file(GLOB _sources *.cpp)
-psn00bsdk_add_executable(cppdemo GPREL ${_sources})
-#psn00bsdk_add_cd_image(cppdemo_iso cppdemo iso.xml DEPENDS cppdemo)
-
-install(FILES ${PROJECT_BINARY_DIR}/cppdemo.exe TYPE BIN)
diff --git a/examples/beginner/cppdemo/main.cpp b/examples/beginner/cppdemo/main.cpp
deleted file mode 100644
index f55f952..0000000
--- a/examples/beginner/cppdemo/main.cpp
+++ /dev/null
@@ -1,151 +0,0 @@
-/* Work in progress example, need to add comments.
- *
- * Basically a quick little example that showcases C++ classes are
- * functioning in PSn00bSDK. - Lameguy64
- *
- * First written in December 18, 2020.
- *
- * Changelog:
- *
- *  May 11, 2023 - Updated the example to use C++ standard library headers,
- *                 renamed the class and cleaned up some methods.
- *  May 10, 2021 - Variable types updated for psxgpu.h changes.
- *
- */
-
-#include <cstddef>
-#include <cstdint>
-#include <cstdio>
-#include <cstdlib>
-#include <psxgte.h>
-#include <psxgpu.h>
-
-/* Example class */
-
-class RenderContext {
-private:
-	std::uint32_t *_ot[2];
-	std::uint8_t  *_pri[2];
-	std::uint8_t  *_nextpri;
-
-	int _ot_count, _db;
-
-	DISPENV _disp[2];
-	DRAWENV _draw[2];
-
-public:
-	RenderContext(std::size_t ot_len = 8, std::size_t pri_len = 8192);
-	~RenderContext(void);
-	void setupBuffers(int w, int h, int r, int g, int b);
-	void flip(void);
-
-	template<typename T> inline T *addPrimitive(void) {
-		auto pri = reinterpret_cast<T *>(_nextpri);
-		addPrim(_ot[_db], pri);
-
-		_nextpri += sizeof(T);
-		return pri;
-	}
-};
-
-RenderContext::RenderContext(std::size_t ot_len, std::size_t pri_len) {
-	_ot[0] = new std::uint32_t[ot_len];
-	_ot[1] = new std::uint32_t[ot_len];
-
-	_db = 0;
-	_ot_count = ot_len;
-	ClearOTagR(_ot[0], _ot_count);
-	ClearOTagR(_ot[1], _ot_count);
-
-	_pri[0] = new std::uint8_t[pri_len];
-	_pri[1] = new std::uint8_t[pri_len];
-
-	_nextpri = _pri[0];
-
-	std::printf("RenderContext::RenderContext: Buffers allocated.\n");
-}
-
-RenderContext::~RenderContext(void) {
-	delete[] _ot[0];
-	delete[] _ot[1];
-
-	delete[] _pri[0];
-	delete[] _pri[1];
-
-	std::printf("RenderContext::RenderContext: Buffers freed.\n");
-}
-
-void RenderContext::setupBuffers(int w, int h, int r, int g, int b) {
-	SetDefDispEnv(&_disp[0], 0, h, w, h);
-	SetDefDispEnv(&_disp[1], 0, 0, w, h);
-	SetDefDrawEnv(&_draw[0], 0, 0, w, h);
-	SetDefDrawEnv(&_draw[1], 0, h, w, h);
-
-	setRGB0(&_draw[0], r, g, b);
-	_draw[0].isbg = 1;
-	_draw[0].dtd  = 1;
-
-	setRGB0(&_draw[1], r, g, b);
-	_draw[1].isbg = 1;
-	_draw[1].dtd  = 1;
-
-	PutDispEnv(&_disp[0]);
-	PutDrawEnv(&_draw[0]);
-}
-
-void RenderContext::flip(void) {
-	DrawSync(0);
-	VSync(0);
-
-	_db ^= 1;
-
-	PutDispEnv(&_disp[_db]);
-	PutDrawEnv(&_draw[_db]);
-
-	DrawOTag(_ot[_db ^ 1] + _ot_count - 1);
-	ClearOTagR(_ot[_db], _ot_count);
-
-	_nextpri = _pri[_db];
-}
-
-/* Main */
-
-static constexpr int SCREEN_XRES = 320;
-static constexpr int SCREEN_YRES = 240;
-
-static constexpr int BGCOLOR_R =  63;
-static constexpr int BGCOLOR_G =   0;
-static constexpr int BGCOLOR_B = 127;
-
-int main(int argc, const char **argv) {
-	ResetGraph(0);
-	SetDispMask(1);
-
-	RenderContext ctx;
-	ctx.setupBuffers(SCREEN_XRES, SCREEN_YRES, BGCOLOR_R, BGCOLOR_G, BGCOLOR_B);
-
-	int x  = 0, y  = 0;
-	int dx = 1, dy = 1;
-
-	for (;;) {
-		// Update the position and velocity of the bouncing square.
-		if (x < 0 || x > (SCREEN_XRES - 64))
-			dx = -dx;
-		if (y < 0 || y > (SCREEN_YRES - 64))
-			dy = -dy;
-
-		x += dx;
-		y += dy;
-
-		// Draw the square.
-		auto tile = ctx.addPrimitive<TILE>();
-		setTile(tile);
-		setXY0 (tile, x, y);
-		setWH  (tile, 64, 64);
-		setRGB0(tile, 255, 255, 0);
-
-		ctx.flip();
-	}
-
-	return 0;
-}
diff --git a/examples/beginner/hello/main.c b/examples/beginner/hello/main.c
index 1f02f0b..7f738d3 100644
--- a/examples/beginner/hello/main.c
+++ b/examples/beginner/hello/main.c
@@ -1,118 +1,173 @@
-/* 
- * LibPSn00b Example Programs
+/*
+ * PSn00bSDK basic graphics example
+ * (C) 2020-2023 Lameguy64, spicyjpeg - MPL licensed
  *
- * Hello World Example
- * 2019-2020 Meido-Tek Productions / PSn00bSDK Project
+ * A comprehensive "advanced hello world" example showing how to set up the
+ * screen with double buffering, draw basic graphics (a bouncing square) and use
+ * PSn00bSDK's debug font API to quickly print some text, all while following
+ * best practices. This is not necessarily the simplest hello world example and
+ * may look daunting at first glance, but it is a good starting point for more
+ * complex programs.
  *
- * The obligatory hello world example normally included in nearly every
- * SDK package. This example should also get you started in how to manage
- * the display using psxgpu.
+ * In order to avoid cluttering the program with global variables (as many Sony
+ * SDK examples and other PSn00bSDK examples written before this one do) two
+ * custom structures are employed:
  *
- * Example by Lameguy64
+ * - a RenderBuffer structure containing the DISPENV and DRAWENV objects that
+ *   represent the location of the framebuffer in VRAM, as well as the ordering
+ *   table (OT) used to sort GPU commands/primitives by their Z index and the
+ *   actual buffer commands will be written to;
+ * - a RenderContext structure holding two RenderBuffer instances plus some
+ *   variables to keep track of which buffer is currently being drawn and how
+ *   much of its primitive buffer has been filled up so far.
  *
- *
- * Changelog:
- *
- *	  January 1, 2020 - Initial version
+ * A C++ version of this example is also available (see examples/hellocpp).
  */
- 
-#include <stdio.h>
-#include <sys/types.h>
-#include <psxetc.h>
-#include <psxgte.h>
+
+#include <assert.h>
+#include <stddef.h>
+#include <stdint.h>
 #include <psxgpu.h>
 
+// Length of the ordering table, i.e. the range Z coordinates can have, 0-15 in
+// this case. Larger values will allow for more granularity with depth (useful
+// when drawing a complex 3D scene) at the expense of RAM usage and performance.
+#define OT_LENGTH 16
 
-// Define display/draw environments for double buffering
-DISPENV disp[2];
-DRAWENV draw[2];
-int db;
+// Size of the buffer GPU commands and primitives are written to. If the program
+// crashes due to too many primitives being drawn, increase this value.
+#define BUFFER_LENGTH 8192
 
+/* Framebuffer/display list class */
 
-// Init function
-void init(void)
-{
-	// This not only resets the GPU but it also installs the library's
-	// ISR subsystem to the kernel
-	ResetGraph(0);
-	
-	// Define display environments, first on top and second on bottom
-	SetDefDispEnv(&disp[0], 0, 0, 320, 240);
-	SetDefDispEnv(&disp[1], 0, 240, 320, 240);
-	
-	// Define drawing environments, first on bottom and second on top
-	SetDefDrawEnv(&draw[0], 0, 240, 320, 240);
-	SetDefDrawEnv(&draw[1], 0, 0, 320, 240);
-	
-	// Set and enable clear color
-	setRGB0(&draw[0], 0, 96, 0);
-	setRGB0(&draw[1], 0, 96, 0);
-	draw[0].isbg = 1;
-	draw[1].isbg = 1;
-	
-	// Clear double buffer counter
-	db = 0;
-	
-	// Apply the GPU environments
-	PutDispEnv(&disp[db]);
-	PutDrawEnv(&draw[db]);
-	
-	// Load test font
-	FntLoad(960, 0);
-	
-	// Open up a test font text stream of 100 characters
-	FntOpen(0, 8, 320, 224, 0, 100);
+typedef struct {
+	DISPENV disp_env;
+	DRAWENV draw_env;
+
+	uint32_t ot[OT_LENGTH];
+	uint8_t  buffer[BUFFER_LENGTH];
+} RenderBuffer;
+
+typedef struct {
+	RenderBuffer buffers[2];
+	uint8_t      *next_packet;
+	int          active_buffer;
+} RenderContext;
+
+void setup_context(RenderContext *ctx, int w, int h, int r, int g, int b) {
+	// Place the two framebuffers vertically in VRAM.
+	SetDefDrawEnv(&(ctx->buffers[0].draw_env), 0, 0, w, h);
+	SetDefDispEnv(&(ctx->buffers[0].disp_env), 0, 0, w, h);
+	SetDefDrawEnv(&(ctx->buffers[1].draw_env), 0, h, w, h);
+	SetDefDispEnv(&(ctx->buffers[1].disp_env), 0, h, w, h);
+
+	// Set the default background color and enable auto-clearing.
+	setRGB0(&(ctx->buffers[0].draw_env), r, g, b);
+	setRGB0(&(ctx->buffers[1].draw_env), r, g, b);
+	ctx->buffers[0].draw_env.isbg = 1;
+	ctx->buffers[1].draw_env.isbg = 1;
+
+	// Initialize the first buffer and clear its OT so that it can be used for
+	// drawing.
+	ctx->active_buffer = 0;
+	ctx->next_packet   = ctx->buffers[0].buffer;
+	ClearOTagR(ctx->buffers[0].ot, OT_LENGTH);
+
+	// Turn on the video output.
+	SetDispMask(1);
 }
 
-// Display function
-void display(void)
-{
-	// Flip buffer index
-	db = !db;
-	
-	// Wait for all drawing to complete
+void flip_buffers(RenderContext *ctx) {
+	// Wait for the GPU to finish drawing, then wait for vblank in order to
+	// prevent screen tearing.
 	DrawSync(0);
-	
-	// Wait for vertical sync to cap the logic to 60fps (or 50 in PAL mode)
-	// and prevent screen tearing
 	VSync(0);
 
-	// Switch pages	
-	PutDispEnv(&disp[db]);
-	PutDrawEnv(&draw[db]);
-	
-	// Enable display output, ResetGraph() disables it by default
-	SetDispMask(1);
-	
+	RenderBuffer *draw_buffer = &(ctx->buffers[ctx->active_buffer]);
+	RenderBuffer *disp_buffer = &(ctx->buffers[ctx->active_buffer ^ 1]);
+
+	// Display the framebuffer the GPU has just finished drawing and start
+	// rendering the display list that was filled up in the main loop.
+	PutDispEnv(&(disp_buffer->disp_env));
+	DrawOTagEnv(&(draw_buffer->ot[OT_LENGTH - 1]), &(draw_buffer->draw_env));
+
+	// Switch over to the next buffer, clear it and reset the packet allocation
+	// pointer.
+	ctx->active_buffer ^= 1;
+	ctx->next_packet    = disp_buffer->buffer;
+	ClearOTagR(disp_buffer->ot, OT_LENGTH);
 }
 
-// Main function, program entrypoint
-int main(int argc, const char *argv[])
-{
-	int counter;
-
-	// Init stuff	
-	init();
-	
-	// Main loop
-	counter = 0;
-	while(1)
-	{
-	
-		// Print the obligatory hello world and counter to show that the
-		// program isn't locking up to the last created text stream
-		FntPrint(-1, "HELLO WORLD\n");
-		FntPrint(-1, "COUNTER=%d\n", counter);
-		
-		// Draw the last created text stream
-		FntFlush(-1);
-		
-		// Update display
-		display();
-		
-		// Increment the counter
-		counter++;
+void *new_primitive(RenderContext *ctx, int z, size_t size) {
+	// Place the primitive after all previously allocated primitives, then
+	// insert it into the OT and bump the allocation pointer.
+	RenderBuffer *buffer = &(ctx->buffers[ctx->active_buffer]);
+	uint8_t      *prim   = ctx->next_packet;
+
+	addPrim(&(buffer->ot[z]), prim);
+	ctx->next_packet += size;
+
+	// Make sure we haven't yet run out of space for future primitives.
+	assert(ctx->next_packet <= &(buffer->buffer[BUFFER_LENGTH]));
+
+	return (void *) prim;
+}
+
+// A simple helper for drawing text using PSn00bSDK's debug font API. Note that
+// FntSort() requires the debug font texture to be uploaded to VRAM beforehand
+// by calling FntLoad().
+void draw_text(RenderContext *ctx, int x, int y, int z, const char *text) {
+	RenderBuffer *buffer = &(ctx->buffers[ctx->active_buffer]);
+
+	ctx->next_packet = (uint8_t *)
+		FntSort(&(buffer->ot[z]), ctx->next_packet, x, y, text);
+
+	assert(ctx->next_packet <= &(buffer->buffer[BUFFER_LENGTH]));
+}
+
+/* Main */
+
+#define SCREEN_XRES 320
+#define SCREEN_YRES 240
+
+int main(int argc, const char **argv) {
+	// Initialize the GPU and load the default font texture provided by
+	// PSn00bSDK at (960, 0) in VRAM.
+	ResetGraph(0);
+	FntLoad(960, 0);
+
+	// Set up our rendering context.
+	RenderContext ctx;
+	setup_context(&ctx, SCREEN_XRES, SCREEN_YRES, 63, 0, 127);
+
+	int x  = 0, y  = 0;
+	int dx = 1, dy = 1;
+
+	for (;;) {
+		// Update the position and velocity of the bouncing square.
+		if (x < 0 || x > (SCREEN_XRES - 64))
+			dx = -dx;
+		if (y < 0 || y > (SCREEN_YRES - 64))
+			dy = -dy;
+
+		x += dx;
+		y += dy;
+
+		// Draw the square by allocating a TILE (i.e. untextured solid color
+		// rectangle) primitive at Z = 1.
+		TILE *tile = (TILE *) new_primitive(&ctx, 1, sizeof(TILE));
+
+		setTile(tile);
+		setXY0 (tile, x, y);
+		setWH  (tile, 64, 64);
+		setRGB0(tile, 255, 255, 0);
+
+		// Draw some text in front of the square (Z = 0, primitives with higher
+		// Z indices are drawn first).
+		draw_text(&ctx, 8, 16, 0, "Hello world!");
+
+		flip_buffers(&ctx);
 	}
-	
+
 	return 0;
 }
diff --git a/examples/beginner/hellocpp/CMakeLists.txt b/examples/beginner/hellocpp/CMakeLists.txt
new file mode 100644
index 0000000..85f0fde
--- /dev/null
+++ b/examples/beginner/hellocpp/CMakeLists.txt
@@ -0,0 +1,18 @@
+# PSn00bSDK example CMake script
+# (C) 2021 spicyjpeg - MPL licensed
+
+cmake_minimum_required(VERSION 3.21)
+
+project(
+	hellocpp
+	LANGUAGES    CXX
+	VERSION      1.0.0
+	DESCRIPTION  "PSn00bSDK C++ hello world example"
+	HOMEPAGE_URL "http://lameguy64.net/?page=psn00bsdk"
+)
+
+file(GLOB _sources *.cpp)
+psn00bsdk_add_executable(hellocpp GPREL ${_sources})
+#psn00bsdk_add_cd_image(hellocpp_iso hellocpp iso.xml DEPENDS hellocpp)
+
+install(FILES ${PROJECT_BINARY_DIR}/hellocpp.exe TYPE BIN)
diff --git a/examples/beginner/hellocpp/main.cpp b/examples/beginner/hellocpp/main.cpp
new file mode 100644
index 0000000..20923be
--- /dev/null
+++ b/examples/beginner/hellocpp/main.cpp
@@ -0,0 +1,232 @@
+/*
+ * PSn00bSDK C++ basic graphics example
+ * (C) 2020-2023 Lameguy64, spicyjpeg - MPL licensed
+ *
+ * A C++ variant of the beginner/hello example showcasing the use of classes and
+ * templates in place of structures, making the code more readable and less
+ * error-prone. The OT and primitive buffer are now allocated on the heap and
+ * automatically freed when the RenderContext class is destroyed or goes out of
+ * scope.
+ *
+ * See the original example for more details.
+ */
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <psxgpu.h>
+
+static constexpr size_t DEFAULT_OT_LENGTH     = 15;
+static constexpr size_t DEFAULT_BUFFER_LENGTH = 8192;
+
+/* RenderBuffer class */
+
+class RenderBuffer {
+private:
+	DISPENV _disp_env;
+	DRAWENV _draw_env;
+
+	std::uint32_t *_ot;
+	std::uint8_t  *_buffer;
+	std::size_t   _ot_length, _buffer_length;
+
+public:
+	RenderBuffer(std::size_t ot_length, std::size_t buffer_length);
+	~RenderBuffer(void);
+	void setup(int x, int y, int w, int h, int r, int g, int b);
+
+	inline uint8_t *buffer_start(void) const {
+		return _buffer;
+	}
+	inline uint8_t *buffer_end(void) const {
+		return &_buffer[_buffer_length];
+	}
+	inline uint32_t *ot_entry(int z) const {
+		//assert((z >= 0) && (z < _ot_length));
+		return &_ot[z];
+	}
+
+	inline void clear_ot(void) {
+		ClearOTagR(_ot, _ot_length);
+	}
+	inline void draw(void) {
+		DrawOTagEnv(&_ot[_ot_length - 1], &_draw_env);
+	}
+	inline void display(void) const {
+		PutDispEnv(&_disp_env);
+	}
+};
+
+RenderBuffer::RenderBuffer(std::size_t ot_length, std::size_t buffer_length)
+: _ot_length(ot_length), _buffer_length(buffer_length) {
+	// Initializing the OT in a constructor is unsafe, since ClearOTagR()
+	// requires DMA to be enabled and may fail if called before ResetGraph() or
+	// ResetCallback() (which can easily happen as constructors can run before
+	// main()). Thus, this constructor is only going to allocate the buffers and
+	// clearing is deferred to RenderContext::setup().
+	_ot     = new uint32_t[ot_length];
+	_buffer = new uint8_t[buffer_length];
+
+	assert(_ot && _buffer);
+
+	//std::printf("Allocated buffer, ot=0x%08x, buffer=0x%08x\n", ot, buffer);
+}
+
+RenderBuffer::~RenderBuffer(void) {
+	delete[] _ot;
+	delete[] _buffer;
+
+	//std::printf("Freed buffer, ot=0x%08x, buffer=0x%08x\n", ot, buffer);
+}
+
+void RenderBuffer::setup(int x, int y, int w, int h, int r, int g, int b) {
+	// Set the framebuffer's VRAM coordinates.
+	SetDefDrawEnv(&_draw_env, x, y, w, h);
+	SetDefDispEnv(&_disp_env, x, y, w, h);
+
+	// Set the default background color and enable auto-clearing.
+	setRGB0(&_draw_env, r, g, b);
+	_draw_env.isbg = 1;
+}
+
+/* RenderContext class */
+
+class RenderContext {
+private:
+	RenderBuffer _buffers[2];
+	std::uint8_t *_next_packet;
+	int          _active_buffer;
+
+	// These functions are simply shorthands for _buffers[_active_buffer] and
+	// _buffers[_active_buffer ^ 1] respectively. They are only used internally.
+	inline RenderBuffer &_draw_buffer(void) {
+		return _buffers[_active_buffer];
+	}
+	inline RenderBuffer &_disp_buffer(void) {
+		return _buffers[_active_buffer ^ 1];
+	}
+
+public:
+	RenderContext(
+		std::size_t ot_length     = DEFAULT_OT_LENGTH,
+		std::size_t buffer_length = DEFAULT_BUFFER_LENGTH
+	);
+	void setup(int w, int h, int r, int g, int b);
+	void flip(void);
+
+	// This is a "factory function" that allocates a new primitive within the
+	// currently active buffer. It is a template method, meaning T will get
+	// replaced at compile time by the type of the primitive we are going to
+	// allocate (and sizeof(T) will change accordingly!).
+	template<typename T> inline T *new_primitive(int z = 0) {
+		// Place the primitive after all previously allocated primitives, then
+		// insert it into the OT and bump the allocation pointer.
+		auto prim = reinterpret_cast<T *>(_next_packet);
+
+		addPrim(_draw_buffer().ot_entry(z), prim);
+		_next_packet += sizeof(T);
+
+		// Make sure we haven't yet run out of space for future primitives.
+		assert(_next_packet <= _draw_buffer().buffer_end());
+
+		return prim;
+	}
+
+	// A simple helper for drawing text using PSn00bSDK's debug font API. Note
+	// that FntSort() requires the debug font texture to be uploaded to VRAM
+	// beforehand by calling FntLoad().
+	inline void draw_text(int x, int y, int z, const char *text) {
+		_next_packet = reinterpret_cast<uint8_t *>(
+			FntSort(_draw_buffer().ot_entry(z), _next_packet, x, y, text)
+		);
+
+		assert(_next_packet <= _draw_buffer().buffer_end());
+	}
+};
+
+RenderContext::RenderContext(std::size_t ot_length, std::size_t buffer_length)
+: _buffers{
+		RenderBuffer(ot_length, buffer_length),
+		RenderBuffer(ot_length, buffer_length)
+} {}
+
+void RenderContext::setup(int w, int h, int r, int g, int b) {
+	// Place the two framebuffers vertically in VRAM.
+	_buffers[0].setup(0, 0, w, h, r, g, b);
+	_buffers[1].setup(0, h, w, h, r, g, b);
+
+	// Initialize the first buffer and clear its OT so that it can be used for
+	// drawing.
+	_active_buffer = 0;
+	_next_packet   = _draw_buffer().buffer_start();
+	_draw_buffer().clear_ot();
+
+	// Turn on the video output.
+	SetDispMask(1);
+}
+
+void RenderContext::flip(void) {
+	// Wait for the GPU to finish drawing, then wait for vblank in order to
+	// prevent screen tearing.
+	DrawSync(0);
+	VSync(0);
+
+	// Display the framebuffer the GPU has just finished drawing and start
+	// rendering the display list that was filled up in the main loop.
+	_disp_buffer().display();
+	_draw_buffer().draw();
+
+	// Switch over to the next buffer, clear it and reset the packet allocation
+	// pointer.
+	_active_buffer ^= 1;
+	_next_packet    = _draw_buffer().buffer_start();
+	_draw_buffer().clear_ot();
+}
+
+/* Main */
+
+static constexpr int SCREEN_XRES = 320;
+static constexpr int SCREEN_YRES = 240;
+
+int main(int argc, const char **argv) {
+	// Initialize the GPU and load the default font texture provided by
+	// PSn00bSDK at (960, 0) in VRAM.
+	ResetGraph(0);
+	FntLoad(960, 0);
+
+	// Set up our rendering context.
+	RenderContext ctx;
+	ctx.setup(SCREEN_XRES, SCREEN_YRES, 63, 0, 127);
+
+	int x  = 0, y  = 0;
+	int dx = 1, dy = 1;
+
+	for (;;) {
+		// Update the position and velocity of the bouncing square.
+		if (x < 0 || x > (SCREEN_XRES - 64))
+			dx = -dx;
+		if (y < 0 || y > (SCREEN_YRES - 64))
+			dy = -dy;
+
+		x += dx;
+		y += dy;
+
+		// Draw the square by allocating a TILE (i.e. untextured solid color
+		// rectangle) primitive at Z = 1.
+		auto tile = ctx.new_primitive<TILE>(1);
+
+		setTile(tile);
+		setXY0 (tile, x, y);
+		setWH  (tile, 64, 64);
+		setRGB0(tile, 255, 255, 0);
+
+		// Draw some text in front of the square (Z = 0, primitives with higher
+		// Z indices are drawn first).
+		ctx.draw_text(8, 16, 0, "Hello from C++!");
+
+		ctx.flip();
+	}
+
+	return 0;
+}