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

Last change on this file since 3993 was 3570, checked in by Sam Hocevar, 11 years ago

Add a null driver that does absolutely nothing.

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