arsd.pixmappresenter

Pixmap Presenter is a high-level display library for one specific scenario: Blitting fully-rendered frames to the screen.

This is useful for software-rendered applications. Think of old-skool games, emulators etc.

This library builds upon arsd.simpledisplay and arsd.color. It wraps a SimpleWindow and displays the provided frame data. Each frame is automatically centered on, and optionally scaled to, the carrier window. This processing is done with hardware acceleration (OpenGL). Later versions might add a software-mode.

Several scaling modes are supported. Most notably contain that scales pixmaps to the window’s current size while preserving the original aspect ratio. See Scaling for details.

Usage examples

Basic usage

This example displays a blue frame that increases in color intensity, then jumps back to black and the process repeats.

void main() {
	// Internal resolution of the images (“frames”) we will render.
	// From the PixmapPresenter’s perspective,
	// these are the “fully-rendered frames” that it will blit to screen.
	// They may be up- & down-scaled to the window’s actual size
	// (according to the chosen scaling mode) by the presenter.
	const resolution = Size(240, 120);

	// Let’s create a new presenter.
	// (For more fine-grained control there’s also a constructor overload that
	// accepts a [PresenterConfig] instance).
	auto presenter = new PixmapPresenter(
		"Demo",         // window title
		resolution,     // internal resolution
		Size(960, 480), // initial window size (optional; default: =resolution)
	);

	// This variable will be “shared” across events (and frames).
	int blueChannel = 0;

	// Run the eventloop.
	// The callback delegate will get executed every ~16ms (≙ ~60FPS) and schedule a redraw.
	presenter.eventLoop(16, delegate() {
		// Update the pixmap (“framebuffer”) here…

		// Construct an RGB color value.
		auto color = Pixel(0x00, 0x00, blueChannel);
		// For demo purposes, apply it to the whole pixmap.
		presenter.framebuffer.clear(color);

		// Increment the amount of blue to be used by the next frame.
		++blueChannel;
		// reset if greater than 0xFF (=ubyte.max)
		if (blueChannel > 0xFF)
			blueChannel = 0;
	});
}

Minimal example

void main() {
	auto pmp = new PixmapPresenter("My Pixmap App", Size(640, 480));
	pmp.framebuffer.clear(rgb(0xFF, 0x00, 0x99));
	pmp.eventLoop();
}

Advanced example

1 import arsd.pixmappresenter;
2 
3 int main() {
4 	// Internal resolution of the images (“frames”) we will render.
5 	// For further details, check out the “Basic usage” example.
6 	const resolution = Size(240, 120);
7 
8 	// Configure our presenter in advance.
9 	auto cfg = PresenterConfig();
10 	cfg.window.title = "Demo II";
11 	cfg.window.size = Size(960, 480);
12 	cfg.renderer.resolution = resolution;
13 	cfg.renderer.scaling = Scaling.integer; // integer scaling
14 	                                        // → The frame on-screen will
15 	                                        // always have a size that is a
16 	                                        // multiple of the internal
17 	                                        // resolution.
18 	                                        // → Also check out the
19 	                                        // `intHybrid` scaling mode.
20 	// The gentle reader might have noticed that integer scaling will result
21 	// in a padding/border area around the image for most window sizes.
22 	// How about changing its color?
23 	cfg.renderer.background = ColorF(Pixel.white);
24 
25 	// Let’s instantiate a new presenter with the previously created config.
26 	auto presenter = new PixmapPresenter(cfg);
27 
28 	// Start with a green frame, so we can easily observe what’s going on.
29 	presenter.framebuffer.clear(rgb(0x00, 0xDD, 0x00));
30 
31 	int line = 0;
32 	ubyte color = 0;
33 	byte colorDelta = 2;
34 
35 	// Run the eventloop.
36 	// Note how the callback delegate returns a [LoopCtrl] instance.
37 	return presenter.eventLoop(delegate() {
38 		// Determine the start and end index of the current line in the
39 		// framebuffer.
40 		immutable x0 = line * resolution.width;
41 		immutable x1 = x0 + resolution.width;
42 
43 		// Change the color of the current line
44 		presenter.framebuffer.data[x0 .. x1] = rgb(color, color, 0xFF);
45 
46 		// Determine the color to use for the next line
47 		// (to be applied on the next update).
48 		color += colorDelta;
49 		if (color == 0x00)
50 			colorDelta = 2;
51 		else if (color >= 0xFE)
52 			colorDelta = -2;
53 
54 		// Increment the line counter; reset to 0 once we’ve reached the
55 		// end of the framebuffer (=the final/last line).
56 		++line;
57 		if (line == resolution.height)
58 			line = 0;
59 
60 		// Schedule a redraw in ~16ms.
61 		return LoopCtrl.redrawIn(16);
62 	}, delegate(MouseEvent ev) {
63 		// toggle fullscreen mode on double-click
64 		if (ev.doubleClick) {
65 			presenter.toggleFullscreen();
66 		}
67 	});
68 }