source: libcaca/trunk/caca/caca.c @ 2138

Last change on this file since 2138 was 2138, checked in by Sam Hocevar, 12 years ago
  • Implement caca_create_display_with_driver() to specify an output driver without using environment variables..
  • Implement caca_get_display_driver() to return the current display's output driver.
  • Add a simple example program to test caca_create_display_with_driver().
  • Property svn:keywords set to Id
File size: 10.8 KB
Line 
1/*
2 *  libcaca       Colour ASCII-Art library
3 *  Copyright (c) 2006 Sam Hocevar <sam@zoy.org>
4 *                All Rights Reserved
5 *
6 *  $Id: caca.c 2138 2007-12-16 01:50:41Z sam $
7 *
8 *  This library is free software. It comes without any warranty, to
9 *  the extent permitted by applicable law. You can redistribute it
10 *  and/or modify it under the terms of the Do What The Fuck You Want
11 *  To Public License, Version 2, as published by Sam Hocevar. See
12 *  http://sam.zoy.org/wtfpl/COPYING for more details.
13 */
14
15/*
16 *  This file contains the main functions used by \e libcaca applications to
17 *  initialise the library, get the screen properties, set the framerate and
18 *  so on.
19 */
20
21#include "config.h"
22#include "common.h"
23
24#if !defined(__KERNEL__)
25#   include <stdlib.h>
26#   include <string.h>
27#   include <stdio.h>
28#   if defined(USE_PLUGINS)
29#       if defined(HAVE_DLFCN_H)
30#           include <dlfcn.h>
31#       endif
32#   endif
33#endif
34
35#include "cucul.h"
36#include "caca.h"
37#include "caca_internals.h"
38
39#if defined(USE_PLUGINS)
40#   define gl_install(p) caca_plugin_install(p, "gl")
41#   define x11_install(p) caca_plugin_install(p, "x11")
42#endif
43
44static int caca_can_resize(caca_display_t *);
45static int caca_select_driver(caca_display_t *, char const *);
46#if defined(USE_PLUGINS)
47static int caca_plugin_install(char const *, caca_display_t *);
48#endif
49
50/** \brief Attach a caca graphical context to a cucul canvas.
51 *
52 *  Create a graphical context using device-dependent features (ncurses for
53 *  terminals, an X11 window, a DOS command window...) that attaches to a
54 *  libcucul canvas. Everything that gets drawn in the libcucul canvas can
55 *  then be displayed by the libcaca driver.
56 *
57 *  If no cucul canvas is provided, a new one is created. Its handle can be
58 *  retrieved using caca_get_canvas() and it is automatically destroyed when
59 *  caca_free_display() is called.
60 *
61 *  See also caca_create_display_with_driver().
62 *
63 *  If an error occurs, NULL is returned and \b errno is set accordingly:
64 *  - \c ENOMEM Not enough memory.
65 *  - \c ENODEV Graphical device could not be initialised.
66 *
67 *  \param cv The cucul canvas or NULL to create a canvas automatically.
68 *  \return The caca graphical context or NULL if an error occurred.
69 */
70caca_display_t * caca_create_display(cucul_canvas_t *cv)
71{
72    return caca_create_display_with_driver(cv, NULL);
73}
74
75/** \brief Attach a caca graphical context to a cucul canvas.
76 *
77 *  Create a graphical context using device-dependent features (ncurses for
78 *  terminals, an X11 window, a DOS command window...) that attaches to a
79 *  libcucul canvas. Everything that gets drawn in the libcucul canvas can
80 *  then be displayed by the libcaca driver.
81 *
82 *  If no cucul canvas is provided, a new one is created. Its handle can be
83 *  retrieved using caca_get_canvas() and it is automatically destroyed when
84 *  caca_free_display() is called.
85 *
86 *  See also caca_create_display().
87 *
88 *  If an error occurs, NULL is returned and \b errno is set accordingly:
89 *  - \c ENOMEM Not enough memory.
90 *  - \c ENODEV Graphical device could not be initialised.
91 *
92 *  \param cv The cucul canvas or NULL to create a canvas automatically.
93 *  \param driver A string describing the desired output driver or NULL to
94 *                choose the best driver automatically.
95 *  \return The caca graphical context or NULL if an error occurred.
96 */
97caca_display_t * caca_create_display_with_driver(cucul_canvas_t *cv,
98                                                 char const *driver)
99{
100    caca_display_t *dp = malloc(sizeof(caca_display_t));
101
102    if(!dp)
103    {
104        seterrno(ENOMEM);
105        return NULL;
106    }
107
108    if((dp->autorelease = (cv == NULL)))
109    {
110        cv = cucul_create_canvas(0, 0);
111    }
112
113    dp->cv = cv;
114
115    if(cucul_manage_canvas(cv, (int (*)(void *))caca_can_resize, (void *)dp))
116    {
117        if(dp->autorelease)
118            cucul_free_canvas(dp->cv);
119        free(dp);
120        seterrno(EBUSY);
121        return NULL;
122    }
123
124#if defined(USE_PLUGINS)
125    dp->plugin = NULL;
126#endif
127
128    if(caca_select_driver(dp, driver))
129    {
130#if defined(USE_PLUGINS)
131        if(dp->plugin)
132            dlclose(dp->plugin);
133#endif
134        cucul_unmanage_canvas(cv, (int (*)(void *))caca_can_resize, (void *)dp);
135        if(dp->autorelease)
136            cucul_free_canvas(dp->cv);
137        free(dp);
138        seterrno(ENODEV);
139        return NULL;
140    }
141
142    if(dp->drv.init_graphics(dp))
143    {
144#if defined(USE_PLUGINS)
145        if(dp->plugin)
146            dlclose(dp->plugin);
147#endif
148        cucul_unmanage_canvas(cv, (int (*)(void *))caca_can_resize, (void *)dp);
149        if(dp->autorelease)
150            cucul_free_canvas(dp->cv);
151        free(dp);
152        seterrno(ENODEV);
153        return NULL;
154    }
155
156    /* Graphics stuff */
157    dp->delay = 0;
158    dp->rendertime = 0;
159
160    /* Events stuff */
161#if defined(USE_SLANG) || defined(USE_NCURSES)
162    dp->events.key_timer.last_sec = 0;
163    dp->events.key_timer.last_usec = 0;
164    dp->events.last_key_ticks = 0;
165    dp->events.autorepeat_ticks = 0;
166    dp->events.last_key_event.type = CACA_EVENT_NONE;
167#endif
168#if defined(USE_SLANG) || defined(USE_NCURSES) || defined(USE_CONIO) || defined(USE_GL)
169    dp->events.queue = 0;
170#endif
171
172    dp->timer.last_sec = 0;
173    dp->timer.last_usec = 0;
174    dp->lastticks = 0;
175
176    /* Mouse position */
177    dp->mouse.x = cucul_get_canvas_width(dp->cv) / 2;
178    dp->mouse.y = cucul_get_canvas_height(dp->cv) / 2;
179
180    /* Resize events */
181    dp->resize.resized = 0;
182    dp->resize.allow = 0;
183
184    return dp;
185}
186
187/** \brief Return the current output driver
188 *
189 *  Return the given display's current output driver.
190 *
191 *  This function never fails.
192 *
193 *  \param dp The caca display.
194 *  \return A static string.
195 */
196char const * caca_get_display_driver(caca_display_t *dp)
197{
198    return dp->drv.driver;
199}
200
201/** \brief Detach a caca graphical context from a cucul backend context.
202 *
203 *  Detach a graphical context from its cucul backend and destroy it. The
204 *  libcucul canvas continues to exist and other graphical contexts can be
205 *  attached to it afterwards.
206 *
207 *  If the cucul canvas was automatically created by caca_create_display(),
208 *  it is automatically destroyed and any handle to it becomes invalid.
209 *
210 *  This function never fails.
211 *
212 *  \param dp The libcaca graphical context.
213 *  \return This function always returns 0.
214 */
215int caca_free_display(caca_display_t *dp)
216{
217    dp->drv.end_graphics(dp);
218#if defined(USE_PLUGINS)
219    if(dp->plugin)
220        dlclose(dp->plugin);
221#endif
222    cucul_unmanage_canvas(dp->cv, (int (*)(void *))caca_can_resize, (void *)dp);
223    if(dp->autorelease)
224        cucul_free_canvas(dp->cv);
225    free(dp);
226
227    return 0;
228}
229
230/** \brief Get the canvas attached to a caca graphical context.
231 *
232 *  Return a handle on the \e cucul_canvas_t object that was either attached
233 *  or created by caca_create_display().
234 *
235 *  This function never fails.
236 *
237 *  \param dp The libcaca graphical context.
238 *  \return The libcucul canvas.
239 */
240cucul_canvas_t * caca_get_canvas(caca_display_t *dp)
241{
242    return dp->cv;
243}
244
245/** \brief Return the \e libcaca version.
246 *
247 *  Return a read-only string with the \e libcaca version information.
248 *
249 *  This function never fails.
250 *
251 *  \return The \e libcaca version information.
252 */
253char const * caca_get_version(void)
254{
255    return VERSION;
256}
257
258/** \brief Get available display drivers
259 *
260 *  Return a list of available display drivers. The list is a NULL-terminated
261 *  array of strings, interleaving a string containing the internal value for
262 *  the display driver, and a string containing the natural language
263 *  description for that driver.
264 *
265 *  This function never fails.
266 *
267 *  \param dp Display object.
268 *  \return An array of strings.
269 */
270char const * const * caca_get_display_driver_list(void)
271{
272    static char const * const list[] =
273    {
274#if defined(USE_COCOA)
275        "cocoa", "Mac OS X Cocoa",
276#endif
277#if defined(USE_WIN32)
278        "win32", "Windows console",
279#endif
280#if defined(USE_CONIO)
281        "conio", "MS-DOS conio",
282#endif
283#if defined(USE_X11)
284        "x11", "X11 graphical window",
285#endif
286#if defined(USE_GL)
287        "gl", "OpenGL window",
288#endif
289#if !defined(__KERNEL__)
290        "raw", "raw libcaca output",
291#endif
292#if defined(USE_SLANG)
293        "slang", "S-Lang console library",
294#endif
295#if defined(USE_NCURSES)
296        "ncurses", "ncurses console library",
297#endif
298#if defined(USE_VGA)
299        "vga", "direct VGA memory",
300#endif
301        NULL, NULL
302    };
303
304    return list;
305}
306
307/*
308 * XXX: The following functions are local.
309 */
310
311static int caca_can_resize(caca_display_t *dp)
312{
313    return dp->resize.allow;
314}
315
316static int caca_select_driver(caca_display_t *dp, char const *driver)
317{
318    char const *var = driver;
319#if defined(HAVE_GETENV)
320    if(!var)
321        var = getenv("CACA_DRIVER");
322#endif
323
324#if defined(HAVE_STRCASECMP)
325    /* If the environment variable was set, use it */
326    if(var && *var)
327    {
328#if defined(USE_COCOA)
329        if(!strcasecmp(var, "cocoa")) return cocoa_install(dp);
330#endif
331#if defined(USE_WIN32)
332        if(!strcasecmp(var, "win32")) return win32_install(dp);
333#endif
334#if defined(USE_CONIO)
335        if(!strcasecmp(var, "conio")) return conio_install(dp);
336#endif
337#if defined(USE_X11)
338        if(!strcasecmp(var, "x11")) return x11_install(dp);
339#endif
340#if defined(USE_GL)
341        if(!strcasecmp(var, "gl")) return gl_install(dp);
342#endif
343#if !defined(__KERNEL__)
344        if(!strcasecmp(var, "raw")) return raw_install(dp);
345#endif
346#if defined(USE_SLANG)
347        if(!strcasecmp(var, "slang")) return slang_install(dp);
348#endif
349#if defined(USE_NCURSES)
350        if(!strcasecmp(var, "ncurses")) return ncurses_install(dp);
351#endif
352#if defined(USE_VGA)
353        if(!strcasecmp(var, "vga")) return vga_install(dp);
354#endif
355        return -1;
356    }
357#endif
358
359#if defined(USE_COCOA)
360    if(cocoa_install(dp) == 0) return 0;
361#endif
362#if defined(USE_WIN32)
363    if(win32_install(dp) == 0) return 0;
364#endif
365#if defined(USE_CONIO)
366    if(conio_install(dp) == 0) return 0;
367#endif
368#if defined(USE_VGA)
369    if(vga_install(dp) == 0) return 0;
370#endif
371#if defined(USE_X11)
372    if(x11_install(dp) == 0) return 0;
373#endif
374#if defined(USE_GL)
375    if(gl_install(dp) == 0) return 0;
376#endif
377    /* ncurses has a higher priority than slang because it has better colour
378     * support across terminal types, despite being slightly slower. */
379#if defined(USE_NCURSES)
380    if(ncurses_install(dp) == 0) return 0;
381#endif
382#if defined(USE_SLANG)
383    if(slang_install(dp) == 0) return 0;
384#endif
385
386    return -1;
387}
388
389#if defined(USE_PLUGINS)
390static int caca_plugin_install(caca_display_t *dp, char const *driver)
391{
392    char buf[512];
393    int (*sym) (caca_display_t *);
394
395    sprintf(buf, "%s/lib%s_plugin.so", PLUGINDIR, driver);
396    dp->plugin = dlopen(buf, RTLD_NOW);
397    if(!dp->plugin)
398    {
399        sprintf(buf, "lib%s_plugin.so", driver);
400        dp->plugin = dlopen(buf, RTLD_NOW);
401        if(!dp->plugin)
402            return -1;
403    }
404
405    sprintf(buf, "%s_install", driver);
406    sym = dlsym(dp->plugin, buf);
407    if(!sym)
408    {
409        dlclose(dp->plugin);
410        return -1;
411    }
412
413    return sym(dp);
414}
415#endif
416
Note: See TracBrowser for help on using the repository browser.