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

Last change on this file since 4369 was 4369, checked in by sam, 5 years ago

Add the copyright unit test and update copyright information everywhere.

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