* Implemented cucul_get_frame_name() and cucul_set_frame_name().

* Renamed cucul_*_canvas_frame() to cucul_*_frame() because we bloody well
    know that a frame belongs to a canvas.

cucul/canvas.c

@@ -472,16 +472,16 @@ int cucul_set_canvas_boundaries(cucul_canvas_t *cv, int x, int y,
 
     new = cucul_create_canvas(w, h);
 
-    framecount = cucul_get_canvas_frame_count(cv);
+    framecount = cucul_get_frame_count(cv);
     saved_f = cv->frame;
 
     for(f = 0; f < framecount; f++)
     {
         if(f)
-            cucul_create_canvas_frame(new, framecount);
+            cucul_create_frame(new, framecount);
 
-        cucul_set_canvas_frame(cv, f);
-        cucul_set_canvas_frame(new, f);
+        cucul_set_frame(cv, f);
+        cucul_set_frame(new, f);
         cucul_blit(new, -x, -y, cv, NULL);
 
         free(cv->frames[f].chars);
@@ -492,7 +492,7 @@ int cucul_set_canvas_boundaries(cucul_canvas_t *cv, int x, int y,
     memcpy(cv, new, sizeof(cucul_canvas_t));
     free(new);
 
-    cucul_set_canvas_frame(cv, saved_f);
+    cucul_set_frame(cv, saved_f);
 
     return 0;
 }

cucul/cucul.c

@@ -58,6 +58,7 @@ cucul_canvas_t * cucul_create_canvas(unsigned int width, unsigned int height)
         goto nomem;
 
     cv->refcount = 0;
+    cv->autoinc = 0;
 
     cv->frame = 0;
     cv->framecount = 1;
@@ -74,6 +75,7 @@ cucul_canvas_t * cucul_create_canvas(unsigned int width, unsigned int height)
     cv->frames[0].x = cv->frames[0].y = 0;
     cv->frames[0].handlex = cv->frames[0].handley = 0;
     cv->frames[0].curattr = 0;
+    cv->frames[0].name = strdup("frame#00000000");
 
     _cucul_load_frame_info(cv);
     cucul_set_color_ansi(cv, CUCUL_DEFAULT, CUCUL_TRANSPARENT);
@@ -81,6 +83,7 @@ cucul_canvas_t * cucul_create_canvas(unsigned int width, unsigned int height)
     if(_cucul_set_canvas_size(cv, width, height) < 0)
     {
         int saved_errno = geterrno();
+        free(cv->frames[0].name);
         free(cv->frames);
         free(cv);
         seterrno(saved_errno);
@@ -185,6 +188,7 @@ int cucul_free_canvas(cucul_canvas_t *cv)
     {
         free(cv->frames[f].chars);
         free(cv->frames[f].attrs);
+        free(cv->frames[f].name);
     }
 
     free(cv->frames);

cucul/cucul.h

@@ -180,10 +180,12 @@ int cucul_fill_triangle(cucul_canvas_t *, int, int, int, int, int, int,
  *  removal, copying etc.
  *
  *  @{ */
-unsigned int cucul_get_canvas_frame_count(cucul_canvas_t *);
-int cucul_set_canvas_frame(cucul_canvas_t *, unsigned int);
-int cucul_create_canvas_frame(cucul_canvas_t *, unsigned int);
-int cucul_free_canvas_frame(cucul_canvas_t *, unsigned int);
+unsigned int cucul_get_frame_count(cucul_canvas_t *);
+int cucul_set_frame(cucul_canvas_t *, unsigned int);
+char const *cucul_get_frame_name(cucul_canvas_t *);
+int cucul_set_frame_name(cucul_canvas_t *, char const *);
+int cucul_create_frame(cucul_canvas_t *, unsigned int);
+int cucul_free_frame(cucul_canvas_t *, unsigned int);
 /*  @} */
 
 /** \defgroup dither libcucul bitmap dithering
@@ -264,6 +266,14 @@ char const * const * cucul_get_export_list(void);
                         unsigned char) CUCUL_DEPRECATED;
     int cucul_set_truecolor(cucul_canvas_t *, unsigned int,
                             unsigned int) CUCUL_DEPRECATED;
+    unsigned int cucul_get_canvas_frame_count(cucul_canvas_t *)
+                                              CUCUL_DEPRECATED;
+    int cucul_set_canvas_frame(cucul_canvas_t *,
+                               unsigned int) CUCUL_DEPRECATED;
+    int cucul_create_canvas_frame(cucul_canvas_t *,
+                                  unsigned int) CUCUL_DEPRECATED;
+    int cucul_free_canvas_frame(cucul_canvas_t *,
+                                unsigned int) CUCUL_DEPRECATED;
     cucul_buffer_t *cucul_load_memory(void *,
                                       unsigned long int) CUCUL_DEPRECATED;
     cucul_buffer_t *cucul_load_file(char const *) CUCUL_DEPRECATED;

cucul/cucul_internals.h

@@ -31,6 +31,9 @@ struct cucul_frame
     int x, y;
     int handlex, handley;
     uint32_t curattr;
+
+    /* Frame name */
+    char *name;
 };
 
 struct cucul_canvas
@@ -40,6 +43,7 @@ struct cucul_canvas
     struct cucul_frame *frames;
 
     unsigned int refcount;
+    unsigned int autoinc;
 
     /* Shortcut to the active frame information */
     unsigned int width, height;

cucul/frame.c

@@ -36,7 +36,7 @@
  *  \param cv A libcucul canvas
  *  \return The frame count
  */
-unsigned int cucul_get_canvas_frame_count(cucul_canvas_t *cv)
+unsigned int cucul_get_frame_count(cucul_canvas_t *cv)
 {
     return cv->framecount;
 }
@@ -53,24 +53,68 @@ unsigned int cucul_get_canvas_frame_count(cucul_canvas_t *cv)
  *  - \c EINVAL Requested frame is out of range.
  *
  *  \param cv A libcucul canvas
- *  \param frame The canvas frame to activate
+ *  \param id The canvas frame to activate
  *  \return 0 in case of success, -1 if an error occurred.
  */
-int cucul_set_canvas_frame(cucul_canvas_t *cv, unsigned int frame)
+int cucul_set_frame(cucul_canvas_t *cv, unsigned int id)
 {
-    if(frame >= cv->framecount)
+    if(id >= cv->framecount)
     {
         seterrno(EINVAL);
         return -1;
     }
 
     _cucul_save_frame_info(cv);
-    cv->frame = frame;
+    cv->frame = id;
     _cucul_load_frame_info(cv);
 
     return 0;
 }
 
+/** \brief Get the current frame's name.
+ *
+ *  Return the current frame's name. The returned string is valid until
+ *  the frame is deleted or cucul_set_frame_name() is called to change
+ *  the frame name again.
+ *
+ *  This function never fails.
+ *
+ *  \param cv A libcucul canvas.
+ *  \return The current frame's name.
+ */
+char const *cucul_get_frame_name(cucul_canvas_t *cv)
+{
+    return cv->frames[cv->frame].name;
+}
+
+/** \brief Set the current frame's name.
+ *
+ *  Set the current frame's name. Upon creation, a frame has a default name
+ *  of \rc "frame#xxxxxxxx" where \c xxxxxxxx is a self-incrementing
+ *  hexadecimal number.
+ *
+ *  If an error occurs, -1 is returned and \b errno is set accordingly:
+ *  - \c ENOMEM Not enough memory to allocate new frame.
+ *
+ *  \param cv A libcucul canvas.
+ *  \return 0 in case of success, -1 if an error occurred.
+ */
+int cucul_set_frame_name(cucul_canvas_t *cv, char const *name)
+{
+    char *newname = strdup(name);
+
+    if(!newname)
+    {
+        seterrno(ENOMEM);
+        return -1;
+    }
+
+    free(cv->frames[cv->frame].name);
+    cv->frames[cv->frame].name = newname;
+
+    return 0;
+}
+
 /** \brief Add a frame to a canvas.
  *
  *  Create a new frame within the given canvas. Its contents and attributes
@@ -91,7 +135,7 @@ int cucul_set_canvas_frame(cucul_canvas_t *cv, unsigned int frame)
  *  \param id The index where to insert the new frame
  *  \return 0 in case of success, -1 if an error occurred.
  */
-int cucul_create_canvas_frame(cucul_canvas_t *cv, unsigned int id)
+int cucul_create_frame(cucul_canvas_t *cv, unsigned int id)
 {
     unsigned int size = cv->width * cv->height;
     unsigned int f;
@@ -122,6 +166,9 @@ int cucul_create_canvas_frame(cucul_canvas_t *cv, unsigned int id)
     cv->frames[id].handlex = cv->frames[cv->frame].handlex;
     cv->frames[id].handley = cv->frames[cv->frame].handley;
 
+    cv->frames[id].name = strdup("frame#--------");
+    sprintf(cv->frames[id].name + 6, "%.08x", cv->autoinc++);
+
     return 0;
 }
 
@@ -146,7 +193,7 @@ int cucul_create_canvas_frame(cucul_canvas_t *cv, unsigned int id)
  *  \param id The index of the frame to delete
  *  \return 0 in case of success, -1 if an error occurred.
  */
-int cucul_free_canvas_frame(cucul_canvas_t *cv, unsigned int id)
+int cucul_free_frame(cucul_canvas_t *cv, unsigned int id)
 {
     unsigned int f;
 
@@ -164,6 +211,7 @@ int cucul_free_canvas_frame(cucul_canvas_t *cv, unsigned int id)
 
     free(cv->frames[id].chars);
     free(cv->frames[id].attrs);
+    free(cv->frames[id].name);
 
     for(f = id + 1; f < cv->framecount; f++)
         cv->frames[f - 1] = cv->frames[f];

cucul/legacy.c

@@ -106,6 +106,30 @@ cucul_buffer_t * cucul_export_canvas(cucul_canvas_t *cv, char const *format)
     return ex;
 }
 
+/*
+ * Functions from frame.c
+ */
+
+unsigned int cucul_get_canvas_frame_count(cucul_canvas_t *cv)
+{
+    return cucul_get_frame_count(cv);
+}
+
+int cucul_set_canvas_frame(cucul_canvas_t *cv, unsigned int id)
+{
+    return cucul_set_frame(cv, id);
+}
+
+int cucul_create_canvas_frame(cucul_canvas_t *cv, unsigned int id)
+{
+    return cucul_create_frame(cv, id);
+}
+
+int cucul_free_canvas_frame(cucul_canvas_t *cv, unsigned int id)
+{
+    return cucul_free_frame(cv, id);
+}
+
 /*
  * Functions from buffer.c
  */

cxx/cucul++.cpp

@@ -253,19 +253,19 @@ int Cucul::setBoundaries(cucul_canvas_t *, int x, int y,
 
 unsigned int Cucul::getFrameCount()
 {
-    return cucul_get_canvas_frame_count(cv);
+    return cucul_get_frame_count(cv);
 }
 int Cucul::setFrame(unsigned int f)
 {
-    return cucul_set_canvas_frame(cv, f);
+    return cucul_set_frame(cv, f);
 }
 int Cucul::createFrame(unsigned int f)
 {
-    return cucul_create_canvas_frame(cv, f);
+    return cucul_create_frame(cv, f);
 }
 int Cucul::freeFrame(unsigned int f)
 {
-    return cucul_create_canvas_frame(cv, f);
+    return cucul_create_frame(cv, f);
 }
 
 char const *const * Cucul::getImportList(void)

test/all.c

@@ -16,19 +16,19 @@
 
 #if !defined(__KERNEL__)
 #   include <stdio.h>
+#   include <string.h>
 #endif
 
 #include "cucul.h"
 #include "caca.h"
 
-#define ITER 1000
+#define ITER 128
 
 int main(int argc, char *argv[])
 {
     cucul_canvas_t *cv;
-    unsigned int i, w, h;
+    unsigned int i, j, w, h;
 
-    /* cucul_create_canvas */
     fprintf(stderr, "testing cucul_create_canvas()\n");
     for(i = 0; i < ITER; i++)
     {
@@ -41,6 +41,22 @@ int main(int argc, char *argv[])
         cucul_free_canvas(cv);
     }
 
+    fprintf(stderr, "testing cucul_set_frame_name()\n");
+    cv = cucul_create_canvas(1, 1);
+    for(i = 0; i < ITER; i++)
+    {
+        cucul_create_frame(cv, 0);
+        for(j = 0; j < ITER; j++)
+        {
+            char buf[BUFSIZ];
+            w = cucul_rand(1, 1000);
+            memset(buf, 'x', w);
+            buf[w] = '\0';
+            cucul_set_frame_name(cv, buf);
+        }
+    }
+    cucul_free_canvas(cv);
+
     fprintf(stderr, "all tests passed\n");
     return 0;
 }

test/frames.c

@@ -33,7 +33,7 @@ int main(int argc, char *argv[])
     /* Create a canvas with 200 frames */
     cv = cucul_create_canvas(0, 0);
     for(frame = 1; frame < 200; frame++)
-        cucul_create_canvas_frame(cv, frame);
+        cucul_create_frame(cv, frame);
 
     fprintf(stderr, "canvas created, size is %ix%i\n",
             cucul_get_canvas_width(cv), cucul_get_canvas_height(cv));
@@ -47,7 +47,7 @@ int main(int argc, char *argv[])
     /* Fill the first 16 frames with a different colour */
     for(frame = 0; frame < 16; frame++)
     {
-        cucul_set_canvas_frame(cv, frame);
+        cucul_set_frame(cv, frame);
         cucul_set_color_ansi(cv, CUCUL_WHITE, frame);
         cucul_fill_box(cv, 0, 0, 40, 15, ':');
         cucul_set_color_ansi(cv, CUCUL_WHITE, CUCUL_BLUE);
@@ -70,7 +70,7 @@ int main(int argc, char *argv[])
     n = 0;
     while(!caca_get_event(dp, CACA_EVENT_KEY_PRESS, NULL, 0))
     {
-        cucul_set_canvas_frame(cv, n % 16);
+        cucul_set_frame(cv, n % 16);
         caca_refresh_display(dp);
         n++;
     }