software-render

Documentation

Overview

Software rendering to an ANativeWindow.

Demonstrates the pattern for rendering pixels directly to an Android native window using the CPU (software rendering). This is useful for 2D applications, terminal emulators, or any scenario where GPU rendering is not needed.

The window package exposes Window with methods for querying dimensions, setting buffer geometry, and posting rendered frames. The Lock step requires the low-level API because the idiomatic package does not yet wrap ANativeWindow_lock.

Software rendering lifecycle:

1. Obtain -- Get a *Window from the Activity's native surface. The NDK delivers this via ANativeActivity callbacks (onNativeWindowCreated). Wrap the pointer with window.NewWindowFromPointer.

2. Query -- Inspect the window: Width(), Height(), Format(). Width and Height return the current surface dimensions. Format returns an int32 matching a window.Format constant.

3. Configure -- Call SetBuffersGeometry(width, height, format) to request a specific buffer size and pixel format. Pass 0 for any dimension to keep the current value. The compositor scales the buffer to the window size.

4. Lock -- Call ANativeWindow_lock (the low-level layer) to lock the next back-buffer for CPU access. Returns an ANativeWindow_Buffer with pixel memory pointer, width, height, stride, and format. (Not yet exposed in the idiomatic layer.)

5. Draw -- Write pixels into the locked buffer. Respect the stride (pixels per row, may be wider than width due to alignment). The pixel layout depends on the format.

6. Post -- Call UnlockAndPost() to release the buffer and submit it to the compositor for display.

7. Repeat -- Go to step 4 for the next frame.

Pixel formats:

Rgba8888  -- 4 bytes/pixel: [R, G, B, A]
Rgbx8888  -- 4 bytes/pixel: [R, G, B, x] (alpha ignored)
Rgb565    -- 2 bytes/pixel: 5 red, 6 green, 5 blue bits

Prerequisites:

• Android device with a running Activity that provides a native window.
• The window handle is obtained from onNativeWindowCreated.

Because obtaining a window requires an Activity, this example documents the complete software rendering pipeline and prints the API calls rather than invoking them directly.

This program must run on an Android device.