Sketch out a rendering library

svn path=/trunk/netsurf/; revision=4536

Docs/ideas/render-library.txt

@@ -0,0 +1,121 @@
+Rendering library
+=================
+
+General notes
+-------------
+
+ + Potentially long-running routines probably want to exit early and 
+   ask to be resumed (or similar)
+ + There's loads of stuff missing from here (like a typesystem :)
+
+Possible API
+------------
+
+  /* Initialise library */
+  error html_init(void);
+  /* Finalise library */
+  error html_fini(void);
+
+  /* Create a context */
+  ctx   html_create(void);
+  /* Destroy a context */
+  void  html_destroy(ctx);
+
+  /* Configure a context 
+   *
+   * Things that need configuring:
+   *
+   * Callbacks from library -> client:
+   *
+   * + Handler for embedded object fetch requests (how to handle frames?)
+   * + Event notification handler (e.g. form submission / link navigation, 
+   *   mouse pointer shape changing, redraw request, position caret, etc)
+   *
+   * Other stuff:
+   *
+   * + Scale? (should this be handled by the client?)
+   * + Whether to run scripts? (possibly, not needed yet)
+   */
+  error html_setopt(ctx, opttype, optparams);
+
+  /* Feed HTML data to a context */
+  error html_process_data(ctx, data, len);
+  /* Flag end of data to context */
+  error html_data_done(ctx);
+
+  /* Reflow context, to given width/height */
+  error html_reflow(ctx, width, height);
+
+  /* Redraw context, using provided plotters */
+  error html_redraw(ctx, rect, plot_table);
+
+  /* Some kind of input event notification APIs. 
+   * These are called by the client to notify the library 
+   * that something's happened.
+   *
+   * e.g.:
+   */
+  error html_mouse_move(ctx, x, y);
+  error html_mouse_press(ctx, x, y, buttons, modifiers);
+  error html_mouse_release(ctx, x, y, buttons, modifiers);
+  error html_key_press(ctx, key, modifiers);
+  error html_key_release(ctx, key, modifiers);
+  error html_scroll_x(ctx, offset);
+  error html_scroll_y(ctx, offset);
+
+  /* Retrieve properties of document in context 
+   *
+   * e.g.:
+   */
+  error html_get_title(ctx, title);
+
+Example usage
+-------------
+
+/* Main routine */
+main:
+  /* Initialise library */
+  html_init();
+
+  /* Create a context */
+  ctx = html_create();
+
+  /* Configure the context */
+  html_setopt(ctx, FETCH_HANDLER, my_fetcher);
+  html_setopt(ctx, EVENT_HANDLER, my_event_handler);
+
+  /* Get it to process data */
+  foreach (chunk, len) in data:
+    html_process_data(ctx, chunk, len);
+  html_data_done(ctx);
+
+  /* Reflow content to desired dimensions */
+  html_reflow(ctx, width, height);
+
+  /* Main client event loop -- processes UI-toolkit events */
+  do:
+    on mouse event:
+      html_mouse_{move,press,release}(ctx, event.x, event.y ...);
+    on key event:
+      html_key_{press,release}{ctx, event.key, event.modifiers);
+    on scroll event:
+      html_scroll_{x,y}(ctx, event.offset);
+    on redraw event:
+      html_redraw(ctx, event.rect, my_plotters);
+   until quit;
+
+  /* Destroy context */
+  html_destroy(ctx);
+
+  /* Finalise library */
+  html_fini();
+
+/* Event handler for library-generated events */
+my_event_handler:
+  on pointer shape change:
+    set_pointer_shape(shape);
+  on redraw request:
+    redraw_window(window);
+  on position caret:
+    position caret(x, y);
+