docs: add some pixman-rendering comments

We didn't use pixman for rendering in kmscon. This documents shows some
code how we could do it but also explains why this would not improve
performance.

Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>

1 files changed, 47 insertions, 0 deletions

diff --git a/docs/pixman.txt b/docs/pixman.txt
new file mode 100644
index 0000000..e42e9d1
--- /dev/null
+++ b/docs/pixman.txt
@@ -0,0 +1,47 @@
+= Pixman accelerated Rendering =
+
+Several people recommended using pixman for 2D blitting to improve performance
+as pixman has assembler-accelerated backends. However, pixman does not provide
+the functions we need.
+Most rendering operations we need, do alpha compositing with a foreground and
+background color. With pixman we would have to do something like:
+
+	pixman_image_t *pdst = pixman_image_create_bits(
+				PIXMAN_x8r8g8b8,
+				width,
+				height,
+				(uint32_t*)dst,
+				rb->stride);
+	pixman_image_t *pmsk = pixman_image_create_bits(
+				PIXMAN_a8,
+				width,
+				height,
+				(uint32_t*)src,
+				req->buf->stride);
+
+	pixman_color_t fcol = { 0xffff, 0xffff, 0xffff, 0xffff };
+	pixman_image_t *psrc = pixman_image_create_solid_fill(
+				&fcol);
+
+	uint32_t bcol = (req->br << 16) | (req->bg << 8) | req->bb;
+	pixman_fill((void*)dst, rb->stride / 4, 32, 0, 0,
+			width, height, bcol);
+
+	pixman_image_composite(PIXMAN_OP_OVER,
+			       psrc, pmsk, pdst,
+			       0, 0, 0, 0, 0, 0,
+			       width, height);
+
+That is, we create pixman-images for the destination and the mask. We could
+save them in the video-display and glyph objects so there is actually no need
+to allocate them dynamically. However, the solid color object can be any RGB
+value and thus it must be allocated for every blit. This is way too heavy and
+pixman should really provide a way to create solid images easier. Preferably
+without any function call.
+But the bigger problem is actually that we have to copy data twice. We need to
+first call pixman_fill() and then pixman_image_composite() to get the
+behavior we want. This totally kills performance.
+
+Profiling pixman_image_composite(), we see that it definitely is better than
+our unoptimized blitters, but we need to add a function which does both
+operations at once to pixman to get a decent performance.