Changeset 268 for libcaca/trunk/src/caca.cTweet

Timestamp:

Dec 23, 2003, 2:27:40 PM (18 years ago)

Author:

Sam Hocevar

Message:

• src/io.c: + Added caca_wait_event(), a blocking caca_get_event().
• src/ examples/: + More documentation.
• doc/doxygen.cfg.in: + doc/doxygen.cfg is now generated by configure, so that we can use

@top_srcdir@ and we no longer need to hardcode PROJECT_NUMBER.

+ Create manpages.

File:

• libcaca/trunk/src/caca.c (modified) (8 diffs)

libcaca/trunk/src/caca.c

@@ -1 +1 @@
 /*
- *   libcaca       ASCII-Art library
- *   Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
- *                 All Rights Reserved
- *
- *   This library is free software; you can redistribute it and/or
- *   modify it under the terms of the GNU Lesser General Public
- *   License as published by the Free Software Foundation; either
- *   version 2 of the License, or (at your option) any later version.
- *
- *   This library is distributed in the hope that it will be useful,
- *   but WITHOUT ANY WARRANTY; without even the implied warranty of
- *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- *   Lesser General Public License for more details.
- *
- *   You should have received a copy of the GNU Lesser General Public
- *   License along with this library; if not, write to the Free Software
- *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
- *   02111-1307  USA
- */
-
-/**  \file caca.c
- *   \version \$Id$
- *   \author Sam Hocevar <sam@zoy.org>
- *   \brief Main \e libcaca functions
- *
- *   This file contains the main functions used by \e libcaca applications to
- *   initialise the library, get the screen properties, set the framerate and
- *   so on.
+ *  libcaca       ASCII-Art library
+ *  Copyright (c) 2002, 2003 Sam Hocevar <sam@zoy.org>
+ *                All Rights Reserved
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+ *  02111-1307  USA
+ */
+
+/** \file caca.c
+ *  \version \$Id$
+ *  \author Sam Hocevar <sam@zoy.org>
+ *  \brief Main \e libcaca functions
+ *
+ *  This file contains the main functions used by \e libcaca applications to
+ *  initialise the library, get the screen properties, set the framerate and
+ *  so on.
  */
 
@@ -62 +62 @@
 #endif
 
-/**
- * \brief Initialise libcaca.
- *
- * \return 0 upon success, a non-zero value if an error occurs.
+/** \brief Initialise \e libcaca.
+ *
+ *  This function initialises internal \e libcaca structures and the backend
+ *  that will be used for subsequent graphical operations. It must be the
+ *  first \e libcaca function to be called in a function. caca_end() should
+ *  be called at the end of the program to free all allocated resources.
+ *
+ *  \return 0 upon success, a non-zero value if an error occurs.
  */
 int caca_init(void)
@@ -154 +158 @@
 }
 
-/**
- * \brief Get the screen width.
- *
- * \return The screen width, in character cells.
+/** \brief Get the screen width.
+ *
+ *  This function returns the current screen width, in character cells.
+ *
+ *  \return The screen width.
  */
 unsigned int caca_get_width(void)
@@ -164 +169 @@
 }
 
-/**
- * \brief Get the screen height.
- *
- * \return The screen height, in character cells.
+/** \brief Get the screen height.
+ *
+ *  This function returns the current screen height, in character cells.
+ *
+ *  \return The screen height.
  */
 unsigned int caca_get_height(void)
@@ -210 +216 @@
 }
 
-/**
- * \brief Get the current value of a feature.
- *
- * \param feature The requested feature.
- * \return The current value of the feature.
+/** \brief Get the current value of a feature.
+ *
+ *  This function retrieves the value of an internal \e libcaca feature. A
+ *  generic feature value is expected, such as CACA_ANTIALIASING.
+ *
+ *  \param feature The requested feature.
+ *  \return The current value of the feature or CACA_UNKNOWN_FEATURE if an
+ *          error occurred..
  */
 enum caca_feature caca_get_feature(enum caca_feature feature)
@@ -232 +241 @@
 }
 
-/**
- * \brief Set a feature.
- *
- * \param feature The wanted feature.
- * \return void
+/** \brief Set a feature.
+ *
+ *  This function sets an internal \e libcaca feature such as the antialiasing
+ *  or dithering modes. If a specific feature such as CACA_DITHERING_RANDOM,
+ *  caca_set_feature() will set it immediately. If a generic feature is given
+ *  instead, such as CACA_DITHERING, the default value will be used instead.
+ *
+ *  \param feature The requested feature.
  */
 void caca_set_feature(enum caca_feature feature)
@@ -299 +311 @@
 }
 
-/**
- * \brief Uninitialise libcaca.
- *
- * \return void
+/** \brief Uninitialise \e libcaca.
+ *
+ *  This function frees all resources allocated by caca_init(). After
+ *  caca_end() has been called, no other \e libcaca functions may be used
+ *  unless a new call to caca_init() is done.
  */
 void caca_end(void)
@@ -346 +359 @@
 #endif
 }
+
+/*
+ * XXX: The following functions are local.
+ */
 
 static void caca_init_driver(void)