source: libcaca/trunk/caca/graphics.c @ 800

Last change on this file since 800 was 773, checked in by Sam Hocevar, 15 years ago
  • Improved documentation in many places.
  • Property svn:keywords set to Id
File size: 5.2 KB
RevLine 
[35]1/*
[672]2 *  libcaca       Colour ASCII-Art library
[527]3 *  Copyright (c) 2002-2006 Sam Hocevar <sam@zoy.org>
[268]4 *                All Rights Reserved
[35]5 *
[769]6 *  $Id: graphics.c 773 2006-04-14 12:10:18Z sam $
7 *
[268]8 *  This library is free software; you can redistribute it and/or
[522]9 *  modify it under the terms of the Do What The Fuck You Want To
10 *  Public License, Version 2, as published by Sam Hocevar. See
11 *  http://sam.zoy.org/wtfpl/COPYING for more details.
[35]12 */
[17]13
[769]14/*
[268]15 *  This file contains character and string drawing functions.
[205]16 */
17
[63]18#include "config.h"
19
[185]20#include "caca.h"
21#include "caca_internals.h"
[524]22#include "cucul.h"
23#include "cucul_internals.h"
[17]24
[343]25/** \brief Set the window title.
26 *
27 *  If libcaca runs in a window, try to change its title. This works with
28 *  the X11 and Win32 drivers.
29 *
[773]30 *  \param kk The libcaca graphical context.
[343]31 *  \param title The desired window title.
32 *  \return 0 upon success, a non-zero value if an error occurs.
33 */
[524]34int caca_set_window_title(caca_t *kk, char const *title)
[343]35{
[550]36    return kk->drv.set_window_title(kk, title);
[343]37}
38
[352]39/** \brief Get the window width.
40 *
41 *  If libcaca runs in a window, get the usable window width. This value can
42 *  be used for aspect ratio calculation. If libcaca does not run in a window
[582]43 *  or if there is no way to know the font size, most drivers will assume a
44 *  6x10 font is being used. Note that the units are not necessarily pixels.
[352]45 *
[773]46 *  \param kk The libcaca graphical context.
[352]47 *  \return The window width.
48 */
[524]49unsigned int caca_get_window_width(caca_t *kk)
[352]50{
[550]51    return kk->drv.get_window_width(kk);
[352]52}
53
54/** \brief Get the window height.
55 *
56 *  If libcaca runs in a window, get the usable window height. This value can
57 *  be used for aspect ratio calculation. If libcaca does not run in a window
58 *  or if there is no way to know the font size, assume a 6x10 font is being
59 *  used. Note that the units are not necessarily pixels.
60 *
[773]61 *  \param kk The libcaca graphical context.
[352]62 *  \return The window height.
63 */
[524]64unsigned int caca_get_window_height(caca_t *kk)
[352]65{
[550]66    return kk->drv.get_window_height(kk);
[352]67}
68
[268]69/** \brief Set the refresh delay.
[257]70 *
[268]71 *  This function sets the refresh delay in microseconds. The refresh delay
[527]72 *  is used by caca_display() to achieve constant framerate. See the
73 *  caca_display() documentation for more details.
[268]74 *
75 *  If the argument is zero, constant framerate is disabled. This is the
76 *  default behaviour.
77 *
[773]78 *  \param kk The libcaca graphical context.
[268]79 *  \param usec The refresh delay in microseconds.
[257]80 */
[524]81void caca_set_delay(caca_t *kk, unsigned int usec)
[227]82{
[524]83    kk->delay = usec;
[227]84}
85
[268]86/** \brief Get the average rendering time.
[257]87 *
[268]88 *  This function returns the average rendering time, which is the average
[527]89 *  measured time between two caca_display() calls, in microseconds. If
[268]90 *  constant framerate was activated by calling caca_set_delay(), the average
91 *  rendering time will not be considerably shorter than the requested delay
92 *  even if the real rendering time was shorter.
93 *
[773]94 *  \param kk The libcaca graphical context.
[268]95 *  \return The render time in microseconds.
[257]96 */
[524]97unsigned int caca_get_rendertime(caca_t *kk)
[227]98{
[524]99    return kk->rendertime;
[227]100}
101
[268]102/** \brief Flush pending changes and redraw the screen.
[257]103 *
[268]104 *  This function flushes all graphical operations and prints them to the
[527]105 *  screen. Nothing will show on the screen until caca_display() is
[331]106 *  called.
[268]107 *
[527]108 *  If caca_set_delay() was called with a non-zero value, caca_display()
[268]109 *  will use that value to achieve constant framerate: if two consecutive
[527]110 *  calls to caca_display() are within a time range shorter than the value
[268]111 *  set with caca_set_delay(), the second call will wait a bit before
112 *  performing the screen refresh.
[773]113 *
114 *  \param kk The libcaca graphical context.
[257]115 */
[527]116void caca_display(caca_t *kk)
[227]117{
[322]118#if !defined(_DOXYGEN_SKIP_ME)
[227]119#define IDLE_USEC 10000
[322]120#endif
[527]121    int ticks = kk->lastticks + _caca_getticks(&kk->timer);
[227]122
[550]123    kk->drv.display(kk);
[261]124
[553]125    /* Once the display is finished, we can ack resizes */
126    if(kk->resize.resized)
[349]127    {
[553]128        kk->resize.resized = 0;
129        _caca_handle_resize(kk);
[349]130    }
[347]131
[524]132    /* Wait until kk->delay + time of last call */
[527]133    ticks += _caca_getticks(&kk->timer);
134    for(ticks += _caca_getticks(&kk->timer);
[524]135        ticks + IDLE_USEC < (int)kk->delay;
[527]136        ticks += _caca_getticks(&kk->timer))
[331]137    {
[335]138        _caca_sleep(IDLE_USEC);
[331]139    }
[227]140
141    /* Update the sliding mean of the render time */
[524]142    kk->rendertime = (7 * kk->rendertime + ticks) / 8;
[227]143
[527]144    kk->lastticks = ticks - kk->delay;
[227]145
146    /* If we drifted too much, it's bad, bad, bad. */
[527]147    if(kk->lastticks > (int)kk->delay)
148        kk->lastticks = 0;
[227]149}
150
[689]151/** \brief Show or hide the mouse pointer.
[686]152 *
[689]153 *  This function shows or hides the mouse pointer, for devices that
154 *  support it.
[686]155 *
[773]156 *  \param kk The libcaca graphical context.
[689]157 *  \param flag 0 hides the pointer, 1 shows the system's default pointer
158 *              (usually an arrow). Other values are reserved for future use.
[686]159 */
[689]160void caca_set_mouse(caca_t *kk, int flag)
[686]161{
[689]162    if(kk->drv.set_mouse)
163        kk->drv.set_mouse(kk, flag);
[686]164}
165
[347]166/*
[511]167 * XXX: following functions are local
[347]168 */
[524]169
[553]170void _caca_handle_resize(caca_t *kk)
[347]171{
[553]172    kk->drv.handle_resize(kk);
[347]173
[527]174    /* Tell libcucul we changed size */
[553]175    if(kk->resize.w != kk->qq->width || kk->resize.h != kk->qq->height)
176        _cucul_set_size(kk->qq, kk->resize.w, kk->resize.h);
[347]177}
178
Note: See TracBrowser for help on using the repository browser.