From 03ad8a42fd7a1b5f0fd8587de28cb6cfdf339963 Mon Sep 17 00:00:00 2001
From: Sam Hocevar <sam@hocevar.net>
Date: Sun, 25 Nov 2007 17:13:08 +0000
Subject: [PATCH]   * Allow caca_create_display()'s argument to be NULL. It
 will automatically     create a canvas when so.   * Add caca_get_canvas() to
 retrieve the cucul canvas.

---
 caca/caca.c           | 38 +++++++++++++++++++++++++++++++++++++-
 caca/caca.h           |  1 +
 caca/caca_internals.h |  1 +
 3 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/caca/caca.c b/caca/caca.c
index fc55fab..c0b4fac 100644
--- a/caca/caca.c
+++ b/caca/caca.c
@@ -54,6 +54,10 @@ static int caca_plugin_install(char const *, caca_display_t *);
  *  libcucul canvas. Everything that gets drawn in the libcucul canvas can
  *  then be displayed by the libcaca driver.
  *
+ *  If no cucul canvas is provided, a new one is created. Its handle can be
+ *  retrieved using caca_get_canvas() and it is automatically destroyed when
+ *  caca_free_display() is called.
+ *
  *  If an error occurs, NULL is returned and \b errno is set accordingly:
  *  - \c ENOMEM Not enough memory.
  *  - \c ENODEV Graphical device could not be initialised.
@@ -71,14 +75,22 @@ caca_display_t * caca_create_display(cucul_canvas_t *cv)
         return NULL;
     }
 
+    if((dp->autorelease = (cv == NULL)))
+    {
+        cv = cucul_create_canvas(0, 0);
+    }
+
+    dp->cv = cv;
+
     if(cucul_manage_canvas(cv, (int (*)(void *))caca_can_resize, (void *)dp))
     {
+        if(dp->autorelease)
+            cucul_free_canvas(dp->cv);
         free(dp);
         seterrno(EBUSY);
         return NULL;
     }
 
-    dp->cv = cv;
 #if defined(USE_PLUGINS)
     dp->plugin = NULL;
 #endif
@@ -90,6 +102,8 @@ caca_display_t * caca_create_display(cucul_canvas_t *cv)
             dlclose(dp->plugin);
 #endif
         cucul_unmanage_canvas(cv, (int (*)(void *))caca_can_resize, (void *)dp);
+        if(dp->autorelease)
+            cucul_free_canvas(dp->cv);
         free(dp);
         seterrno(ENODEV);
         return NULL;
@@ -102,6 +116,8 @@ caca_display_t * caca_create_display(cucul_canvas_t *cv)
             dlclose(dp->plugin);
 #endif
         cucul_unmanage_canvas(cv, (int (*)(void *))caca_can_resize, (void *)dp);
+        if(dp->autorelease)
+            cucul_free_canvas(dp->cv);
         free(dp);
         seterrno(ENODEV);
         return NULL;
@@ -144,6 +160,9 @@ caca_display_t * caca_create_display(cucul_canvas_t *cv)
  *  libcucul canvas continues to exist and other graphical contexts can be
  *  attached to it afterwards.
  *
+ *  If the cucul canvas was automatically created by caca_create_display(),
+ *  it is automatically destroyed and any handle to it becomes invalid.
+ *
  *  This function never fails.
  *
  *  \param dp The libcaca graphical context.
@@ -157,11 +176,28 @@ int caca_free_display(caca_display_t *dp)
         dlclose(dp->plugin);
 #endif
     cucul_unmanage_canvas(dp->cv, (int (*)(void *))caca_can_resize, (void *)dp);
+    if(dp->autorelease)
+        cucul_free_canvas(dp->cv);
     free(dp);
 
     return 0;
 }
 
+/** \brief Get the canvas attached to a caca graphical context.
+ *
+ *  Return a handle on the \e cucul_canvas_t object that was either attached
+ *  or created by caca_create_display().
+ *
+ *  This function never fails.
+ *
+ *  \param dp The libcaca graphical context.
+ *  \return The libcucul canvas.
+ */
+cucul_canvas_t * caca_get_canvas(caca_display_t *dp)
+{
+    return dp->cv;
+}
+
 /*
  * XXX: The following functions are local.
  */
diff --git a/caca/caca.h b/caca/caca.h
index e6d0fea..830dcf1 100644
--- a/caca/caca.h
+++ b/caca/caca.h
@@ -154,6 +154,7 @@ enum caca_key
  *  @{ */
 __extern caca_display_t * caca_create_display(cucul_canvas_t *);
 __extern int caca_free_display(caca_display_t *);
+__extern cucul_canvas_t * caca_get_canvas(caca_display_t *);
 __extern int caca_refresh_display(caca_display_t *);
 __extern int caca_set_display_time(caca_display_t *, unsigned int);
 __extern unsigned int caca_get_display_time(caca_display_t const *);
diff --git a/caca/caca_internals.h b/caca/caca_internals.h
index bf9dbb1..a06ef04 100644
--- a/caca/caca_internals.h
+++ b/caca/caca_internals.h
@@ -108,6 +108,7 @@ struct caca_display
 {
     /* A link to our cucul canvas */
     cucul_canvas_t *cv;
+    int autorelease;
 
 #if defined(USE_PLUGINS)
     void *plugin;