[libfake437] r327 committed - Document display interface.

[libfa...@googlecode.com]

Revision: 327
Author: endgame.dos
Date: Fri Jan 1 19:05:21 2010
Log: Document display interface.
http://code.google.com/p/libfake437/source/detail?r=327

Modified:
/trunk/NOTES
/trunk/include/fake437/display.h
/trunk/src/libfake437/display.c

=======================================
--- /trunk/NOTES Sun Dec 27 18:47:35 2009
+++ /trunk/NOTES Fri Jan 1 19:05:21 2010
@@ -1,2 +1,5 @@
-- Roadmap:
-0.6 - libfcurses?
+0.6 todo:
+- C++ display interface
+
+Roadmap:
+0.7 - libfcurses?
=======================================
--- /trunk/include/fake437/display.h Fri Jan 1 19:05:03 2010
+++ /trunk/include/fake437/display.h Fri Jan 1 19:05:21 2010
@@ -30,25 +30,61 @@
extern "C" {
#endif

+/**
+ ** @deftypefun F437DisplayLayer* f437_display_layer_new @
+ ** (int @var{left}, @
+ ** int @var{top}, @
+ ** int @var{width}, @
+ ** int @var{height})
+ **
+ ** @deftypefunx F437DisplayLayer* f437_display_layer_try_new @
+ ** (int @var{left}, @
+ ** int @var{top}, @
+ ** int @var{width}, @
+ ** int @var{height})
+ **
+ ** Create a F437DisplayLayer with an initial reference count of
+ ** 1. @code{f437_display_layer_new} calls @code{abort()} on
+ ** allocation failure, while @code{f437_display_layer_try_new} just
+ ** returns @code{NULL}.
+ **
+ ** @end deftypefun
+ **/
F437DisplayLayer* f437_display_layer_new(int left, int top,
int width, int height);
F437DisplayLayer* f437_display_layer_try_new(int left, int top,
int width, int height);
+
+/**
+ ** @deftypefun F437DisplayLayer* f437_display_layer_ref @
+ ** (F437DisplayLayer* @var{layer})
+ **
+ ** @deftypefunx void f437_display_layer_unref @
+ ** (F437DisplayLayer* @var{layer})
+ **
+ ** Increment/decrement the reference count of a display
+ ** layer. There's no funny business going on with borrowed references
+ ** or anything - always unref a pointer just before it goes out of
+ ** scope.
+ **
+ ** @end deftypefun
+ **/
F437DisplayLayer* f437_display_layer_ref(F437DisplayLayer* layer);
void f437_display_layer_unref(F437DisplayLayer* layer);

-void f437_display_layer_swap(F437DisplayLayer* a, F437DisplayLayer* b);
-
/**
** @deftypefun F437Display* f437_display_new @
** (F437Surface* @var{surface})
**
- ** @deftypefunx void f437_display_free @
+ ** @deftypefunx F437Display* f437_display_try_new @
+ ** (F437Surface* @var{surface})
+ **
+ ** @deftypefunx F437Surface* f437_display_free @
** (F437Display* @var{display})
**
** Create and destroy @code{F437Display}s. The @code{F437Surface*}
** passed to @code{f437_display_new} will not be owned by the
- ** display.
+ ** display. It will be returned by @code{f437_display_free}.
**
** @end deftypefun
**/
@@ -56,13 +92,61 @@
F437Display* f437_display_try_new(F437Surface* surface);
F437Surface* f437_display_free(F437Display* display);

+/**
+ ** @deftypefun void f437_display_insert_layer @
+ ** (F437Display* @var{display}, @
+ ** F437DisplayLayer* @var{layer}, @
+ ** int @var{n})
+ **
+ ** @deftypefunx F437DisplayLayer* f437_display_get_layer @
+ ** (F437Display* @var{display}, @
+ ** int @var{n})
+ **
+ ** @deftypefunx void f437_display_remove_layer @
+ ** (F437Display* @var{display}, @
+ ** int @var{n})
+ **
+ ** Add/examine/remove a layer from a display. When inserting, the new
+ ** layer is inserted just before layer @var{n}. For get/remove, layer
+ ** @var{n} is returned/removed. For @code{f437_display_get_layer},
+ ** unref the pointer when finished.
+ **
+ ** @end deftypefun
+ **/
void f437_display_insert_layer(F437Display* display, F437DisplayLayer*
layer,
int n);
F437DisplayLayer* f437_display_get_layer(F437Display* display, int n);
void f437_display_remove_layer(F437Display* display, int n);

+/**
+ ** @deftypefun void f437_display_swap_layers @
+ ** (F437Display* @var{display}, @
+ ** int @var{n}, @
+ ** int @var{m})
+ **
+ ** Swap layers @var{n} and @var{m} in the display.
+ **
+ ** @end deftypefun
+ **/
void f437_display_swap_layers(F437Display* display, int n, int m);

+/**
+ ** @deftypefun void f437_display_push_layer @
+ ** (F437Display* @var{display}, @
+ ** F437DisplayLayer* @var{layer})
+ **
+ ** @deftypefunx F437DisplayLayer* f437_display_peek_layer @
+ ** (F437Display* @var{display})
+ **
+ ** @deftypefunx void f437_display_pop_layer @
+ ** (F437Display* @var{display})
+ **
+ ** Treat the display as a stack of layers. For
+ ** @code{f437_display_peek_layer}, be sure to unref the returned
+ ** pointer when finished.
+ **
+ ** @end deftypefun
+ **/
void f437_display_push_layer(F437Display* display, F437DisplayLayer*
layer);
F437DisplayLayer* f437_display_peek_layer(F437Display* display);
void f437_display_pop_layer(F437Display* display);
=======================================
--- /trunk/src/libfake437/display.c Fri Jan 1 19:05:03 2010
+++ /trunk/src/libfake437/display.c Fri Jan 1 19:05:21 2010
@@ -71,15 +71,6 @@
free(layer);
}
}
-
-void f437_display_layer_swap(F437DisplayLayer* a, F437DisplayLayer* b) {
- F437DisplayLayer temp;
- assert(a != NULL);
- assert(b != NULL);
- temp = *a;
- *a = *b;
- *b = temp;
-}

F437Display* f437_display_new(F437Surface* surface) {
F437Display* result = f437_display_try_new(surface);