til_fb: introduce til_fb_fragment_t.ops

There's a need for the ability to efficiently snapshot fragments
via buffer swapping when possible, for modules that want to do
overlay effects which sample the input fragment at arbitrary
pixels other than the one being written to, while producing
output pixels.

Without first making a stable snapshot of the input fragment's
contents, you can't implement such algorithms because you destroy
the input fragment while writing the output pixels.

A simple solution would be to just allocate memory and copy the
input fragment's contents into the allocation, then sample the
copy while writing to the input (now output) fragment's memory.

But when the input fragment represents the entire framebuffer
page/window, it's technically practical to instead simply swap
out the input fragment for a fresh fragment acquired from the
framebuffer/window provider.  Then just sample from the original
fragment while writing to the freshly acquired one now taking the
original's place.

Simple enough.

Except til_fb_fragment_t is also used to describe subfragments
within a larger buffer, and these can't be made discontiguous and
swapped out.  For these fragments there's no escaping the need
for a copy to be made of the contents.  So there needs to be a
way for the fragment itself to furnish an appropriate
snapshotting mechanism, and when what the cloning mechanism
returns can vary.  Depending on the snapshotting mechanism's
implementation, there's also a need for the fragment to furnish
an appropriate free method.  If the snapshot is an entire page
from the native video backend, the backend must free it.  If it's
just libc heap-allocated memory, then a plain old free()
suffices.  If for some reason the memory can't be freed, then a
NULL free() method would be appropriate to simply do nothing.

So this commit introduces such free() and snapshot() methods in
the form of a til_fb_fragment_ops_t struct.  There's no
implementations or use of these as of yet, this is purely
preparatory.

In addition to free() and snapshot(), a submit() method has also
been introduced for submitting ready frames to be displayed.  Not
all fragments may be submitted, only "root" fragments which
represent an entire page from the video backend.  It's these
fragments which will have a non-NULL submit() method, which the
video backend will have initialized appropriately in returning
the page's root fragment.  This is a preparatory change in
anticipation of removing the til_fb_page_t type altogether,
replacing it with a simple til_fb_fragment_t having the
ops.submit() method set.

1 files changed, 7 insertions, 0 deletions

diff --git a/src/til_fb.h b/src/til_fb.h
index c5bf1fe..ff9b3ec 100644
--- a/src/til_fb.h
+++ b/src/til_fb.h
@@ -13,11 +13,18 @@ typedef struct til_fb_fragment_t til_fb_fragment_t;
 
 #define TIL_FB_DRAW_FLAG_TEXTURABLE	0x1
 
+typedef struct til_fb_fragment_ops_t {
+	til_fb_fragment_t *	(*snapshot)(til_fb_fragment_t **fragment_ptr);
+	void			(*submit)(til_fb_fragment_t *fragment);
+	void			(*free)(til_fb_fragment_t *fragment);
+} til_fb_fragment_ops_t;
+
 /* All renderers should target fb_fragment_t, which may or may not represent
  * a full-screen mmap.  Helpers are provided for subdividing fragments for
  * concurrent renderers.
  */
 typedef struct til_fb_fragment_t {
+	til_fb_fragment_ops_t	ops;		/* ops applicable to this fragment */
 	til_fb_fragment_t	*texture;	/* optional source texture when drawing to this fragment */
 	uint32_t		*buf;		/* pointer to the first pixel in the fragment */
 	unsigned		x, y;		/* absolute coordinates of the upper left corner of this fragment */