From 7b481e2d32512b4bb7a27f642fd2f4167b485f18 Mon Sep 17 00:00:00 2001
From: Elias Batek <desisma@heidel.beer>
Date: Fri, 22 Dec 2023 03:29:47 +0100
Subject: [PATCH] Add code examples to pixelpresenter
---
pixelpresenter.d | 113 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 113 insertions(+)
diff --git a/pixelpresenter.d b/pixelpresenter.d
index e36e1b4..55370a5 100644
--- a/pixelpresenter.d
+++ b/pixelpresenter.d
@@ -24,6 +24,119 @@
This module is $(B work in progress).
API is subject to changes until further notice.
)
+
+ ## 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 PixelPresenter’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 PixelPresenter(
+ "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
+ presenter.eventLoop(delegate() {
+ // Update the frame(buffer) here…
+
+ // Construct an RGB color value.
+ auto color = Pixel(0x00, 0x00, blueChannel);
+ // For demo purposes, apply it to the whole framebuffer.
+ 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;
+ });
+ }
+ ---
+
+ ### Advanced example
+
+ ---
+ import arsd.pixelpresenter;
+ import arsd.simpledisplay : MouseEvent;
+
+ void main() {
+ // Internal resolution of the images (“frames”) we will render.
+ // For further details, check out the previous example.
+ const resolution = Size(240, 120);
+
+ // Configure our presenter in advance.
+ auto cfg = PresenterConfig();
+ cfg.window.title = "Demo II";
+ cfg.window.size = Size(960, 480);
+ cfg.renderer.resolution = resolution;
+ cfg.renderer.scaling = Scaling.integer; // integer scaling
+ // → The frame on-screen will
+ // always have a size that is a
+ // multiple of the internal
+ // resolution.
+ // The gentle reader might have noticed that the integer scaling will result
+ // in a padding/border area around the image for most window sizes. Let’s
+ // How about changing its color?
+ cfg.renderer.background = ColorF(Pixel.white);
+
+ // Let’s instantiate a new presenter with the previously created config.
+ auto presenter = new PixelPresenter(cfg);
+
+ // Start with a green frame, so we can easily observe what’s going on.
+ presenter.framebuffer.clear(rgb(0x00, 0xDD, 0x00));
+
+ int line = 0;
+ ubyte color = 0;
+ byte colorDelta = 2;
+
+ // Run the eventloop
+ presenter.eventLoop(delegate() {
+ // Determine the start and end index of the current line in the
+ // framebuffer.
+ immutable x0 = line * resolution.width;
+ immutable x1 = x0 + resolution.width;
+
+ // Change the color of the current line
+ presenter.framebuffer.data[x0 .. x1] = rgb(color, color, 0xFF);
+
+ // Determine the color to use for the next line
+ // (to be applied on the next update).
+ color += colorDelta;
+ if (color == 0x00)
+ colorDelta = 2;
+ else if (color >= 0xFE)
+ colorDelta = -2;
+
+ // Increment the line counter; reset to 0 once we’ve reached the
+ // end of the framebuffer (=the final/last line).
+ ++line;
+ if (line == resolution.height)
+ line = 0;
+ }, delegate(MouseEvent ev) {
+ // toggle fullscreen mode on double-click
+ if (ev.doubleClick) {
+ presenter.isFullscreen = !presenter.isFullscreen;
+ }
+ });
+ ---
+/
module arsd.pixelpresenter;