modules/stub: add a stub sample module

Intended as a bootstrap for new module creation, particularly
aimed at new contributors.  No module context, fragmenting, taps,
or settings are implemented, to keep things as simple as
possible.

3 files changed, 45 insertions, 1 deletions

diff --git a/src/modules/Makefile.am b/src/modules/Makefile.am
index ea82374..aa63268 100644
--- a/src/modules/Makefile.am
+++ b/src/modules/Makefile.am
@@ -1 +1 @@
-SUBDIRS = asc blinds checkers compose drizzle flow flui2d julia meta2d mixer moire montage pixbounce plasma plato ray rkt roto rtv shapes signals snow sparkler spiro stars strobe submit swab swarm voronoi
+SUBDIRS = asc blinds checkers compose drizzle flow flui2d julia meta2d mixer moire montage pixbounce plasma plato ray rkt roto rtv shapes signals snow sparkler spiro stars strobe stub submit swab swarm voronoi
diff --git a/src/modules/stub/Makefile.am b/src/modules/stub/Makefile.am
new file mode 100644
index 0000000..c7f5e2f
--- /dev/null
+++ b/src/modules/stub/Makefile.am
@@ -0,0 +1,3 @@
+noinst_LTLIBRARIES = libstub.la
+libstub_la_SOURCES = stub.c
+libstub_la_CPPFLAGS = -I@top_srcdir@/src
diff --git a/src/modules/stub/stub.c b/src/modules/stub/stub.c
new file mode 100644
index 0000000..b7fabac
--- /dev/null
+++ b/src/modules/stub/stub.c
@@ -0,0 +1,41 @@
+#include "til.h"
+#include "til_fb.h"
+
+/* Sample module fills the frame with white pixels in a non-threaded manner,
+ * replace the body of stub_render_fragment() with your own algorithm.
+ *
+ * To finalize a module implementation derived from this stub, perform a global
+ * substitution of "stub" with your module's name, including copying into
+ * src/modules/$name, and updating all the build system and til.c references.
+ *
+ * A quick way to see what's involved in introducing a new module is to just
+ * `git show` the commit adding this stub module to rototiller.
+ *
+ * XXX: Note that since this module has the TIL_MODULE_EXPERIMENTAL flag set, it
+ * won't appear in the modules list or participate in randomizers.  You can stil
+ * access it explicitly by name via the ":" prefix override, e.g.:
+ * rototiller --module=:stub
+ *
+ * Or just remove the TIL_MODULE_EXPERIMENTAL flag during development so it's
+ * treated normally.
+ */
+
+static void stub_render_fragment(til_module_context_t *context, til_stream_t *stream, unsigned ticks, unsigned cpu, til_fb_fragment_t **fragment_ptr)
+{
+	til_fb_fragment_t	*fragment = *fragment_ptr;
+
+	for (unsigned y = fragment->y; y < fragment->y + fragment->height; y++) {
+		for (unsigned x = fragment->x; x < fragment->x + fragment->width; x++) {
+			til_fb_fragment_put_pixel_unchecked(fragment, 0, x, y, 0xffffffff);
+		}
+	}
+}
+
+
+til_module_t	stub_module = {
+	.render_fragment = stub_render_fragment,
+	.name = "stub",
+	.description = "Minimal stub sample module",
+	.author = "Your Name <your@email.address>",
+	.flags = TIL_MODULE_EXPERIMENTAL,	/* XXX: remove this line to make module generally available */
+};