From 4b406b2a99f21853566392c6d34af633b67c792e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 16:31:24 +0200 Subject: [PATCH 01/11] Moved function doc from condition.h to condition.c --- src/lib/condition.c | 12 ++++++++++++ src/lib/condition.h | 10 ---------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/src/lib/condition.c b/src/lib/condition.c index 0d731f959..795cd121e 100644 --- a/src/lib/condition.c +++ b/src/lib/condition.c @@ -21,6 +21,12 @@ #include "lib/condition.h" + +/** + * Initialize a condition variable + * @param self is a pointer to the condition variable to be initialized + * @return self as given + */ CinelerraCondition cinelerra_condition_init (CinelerraCondition self) { @@ -32,6 +38,12 @@ cinelerra_condition_init (CinelerraCondition self) return self; } + +/** + * Destroy a condition variable + * @param self is a pointer to the condition variable to be destroyed + * @return self as given + */ CinelerraCondition cinelerra_condition_destroy (CinelerraCondition self) { diff --git a/src/lib/condition.h b/src/lib/condition.h index a34ce45ff..67e8175e7 100644 --- a/src/lib/condition.h +++ b/src/lib/condition.h @@ -38,20 +38,10 @@ typedef struct cinelerra_condition_struct cinelerra_condition; typedef cinelerra_condition* CinelerraCondition; -/** - * Initialize a condition variable - * @param self is a pointer to the condition variable to be initialized - * @return self as given - */ CinelerraCondition cinelerra_condition_init (CinelerraCondition self); -/** - * Destroy a condition variable - * @param self is a pointer to the condition variable to be destroyed - * @return self as given - */ CinelerraCondition cinelerra_condition_destroy (CinelerraCondition self); From 6eea8a60e05978182f474586c9b36aa6a6083cdd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 16:52:59 +0200 Subject: [PATCH 02/11] Moved function doc from error.h to error.c --- src/lib/error.c | 11 +++++++++++ src/lib/error.h | 11 ----------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/lib/error.c b/src/lib/error.c index a5268a07f..910db3984 100644 --- a/src/lib/error.c +++ b/src/lib/error.c @@ -39,6 +39,12 @@ cinelerra_error_tls_init (void) pthread_key_create (&cinelerra_error_tls, NULL); } +/** + * Set error state for the current thread. + * If the error state of the current thread was cleared, then set it, else preserve the old state. + * @param err name of the error with 'CINELERRA_ERROR_' prefix (example: CINELERRA_ERROR_NO_MEMORY) + * @return old state, that is NULL for success, when the state was cleared and a pointer to a pending error when the error state was already set + */ const char* cinelerra_error_set (const char * nerr) { @@ -52,6 +58,11 @@ cinelerra_error_set (const char * nerr) } +/** + * Get and clear current error state. + * This function clears the error state, if it needs to be reused, one has to store it in a temporary variable. + * @return pointer to any pending error of this thread, NULL if no error is pending + */ const char* cinelerra_error () { diff --git a/src/lib/error.h b/src/lib/error.h index 071a3c914..21d9dcb73 100644 --- a/src/lib/error.h +++ b/src/lib/error.h @@ -67,20 +67,9 @@ const char* CINELERRA_ERROR_##err = "CINELERRA_ERROR_" #err ":" msg (({ERROR (flag, "%s", strchr(CINELERRA_ERROR_##err, ':')+1);}), \ cinelerra_error_set(CINELERRA_ERROR_##err)) -/** - * Set error state for the current thread. - * If the error state of the current thread was cleared, then set it, else preserve the old state. - * @param err name of the error with 'CINELERRA_ERROR_' prefix (example: CINELERRA_ERROR_NO_MEMORY) - * @return old state, that is NULL for success, when the state was cleared and a pointer to a pending error when the error state was already set - */ const char* cinelerra_error_set (const char * err); -/** - * Get and clear current error state. - * This function clears the error state, if it needs to be reused, one has to store it in a temporary variable. - * @return pointer to any pending error of this thread, NULL if no error is pending - */ const char* cinelerra_error (); From 9e76c6e33ce6a9f008acf30afa07a583176dfd3a Mon Sep 17 00:00:00 2001 From: Christian Thaeter Date: Sat, 20 Oct 2007 16:56:26 +0200 Subject: [PATCH 03/11] seems newer automake dont like the $(builddir) here --- tests/Makefile.am | 12 ++++++------ tests/plugin/Makefile.am | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/Makefile.am b/tests/Makefile.am index d1bd534b2..109cd44b9 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -21,12 +21,12 @@ tests_srcdir = $(top_srcdir)/tests check_PROGRAMS += test-error test_error_SOURCES = $(tests_srcdir)/error/errortest.c test_error_CPPFLAGS = $(AM_CPPFLAGS) -std=gnu99 -Wall -Werror -I$(top_srcdir)/src/ -test_error_LDADD = $(builddir)/libcin3.a -lnobugmt -lpthread -ldl +test_error_LDADD = libcin3.a -lnobugmt -lpthread -ldl check_PROGRAMS += test-time test_time_SOURCES = $(tests_srcdir)/time/test-time.c test_time_CPPFLAGS = $(AM_CPPFLAGS) -std=gnu99 -Wall -Werror -I$(top_srcdir)/src/ -test_time_LDADD = $(builddir)/libcin3.a -lnobugmt -lpthread -ldl -lm +test_time_LDADD = libcin3.a -lnobugmt -lpthread -ldl -lm check_PROGRAMS += test-locking test_locking_SOURCES = \ @@ -34,21 +34,21 @@ test_locking_SOURCES = \ $(tests_srcdir)/locking/mutex.c \ $(tests_srcdir)/locking/condition.c test_locking_CPPFLAGS = $(AM_CPPFLAGS) -std=gnu99 -Wall -Werror -I$(top_srcdir)/src/ -test_locking_LDADD = $(builddir)/libcin3.a -lnobugmt -lpthread -ldl -lm +test_locking_LDADD = libcin3.a -lnobugmt -lpthread -ldl -lm check_PROGRAMS += test-llist test_llist_SOURCES = $(tests_srcdir)/library/test-llist.c test_llist_CPPFLAGS = $(AM_CPPFLAGS) -std=gnu99 -Wall -Werror -I$(top_srcdir)/src/ -test_llist_LDADD = $(builddir)/libcin3.a -lnobugmt -lpthread -ldl -lm +test_llist_LDADD = libcin3.a -lnobugmt -lpthread -ldl -lm check_PROGRAMS += test-references test_references_SOURCES = $(tests_srcdir)/library/test-references.c test_references_CPPFLAGS = $(AM_CPPFLAGS) -std=gnu99 -Wall -Werror -I$(top_srcdir)/src/ -test_references_LDADD = $(builddir)/libcin3.a -lnobugmt -lpthread -ldl -lm -lrt +test_references_LDADD = libcin3.a -lnobugmt -lpthread -ldl -lm -lrt #check_PROGRAMS += test-filehandles #test_filehandles_SOURCES = $(tests_srcdir)/backend/test-filehandles.c #test_filehandles_CPPFLAGS = $(AM_CPPFLAGS) -std=gnu99 -Wall -Werror -I$(top_srcdir)/src/ -#test_filehandles_LDADD = $(builddir)/libcin3backend.a $(builddir)/libcin3.a -lnobugmt -lpthread -ldl -lm +#test_filehandles_LDADD = libcin3backend.a libcin3.a -lnobugmt -lpthread -ldl -lm TESTS = $(tests_srcdir)/test.sh diff --git a/tests/plugin/Makefile.am b/tests/plugin/Makefile.am index 7beeacc75..fa5d52962 100644 --- a/tests/plugin/Makefile.am +++ b/tests/plugin/Makefile.am @@ -20,7 +20,7 @@ noinst_PROGRAMS += test-plugin test_plugin_CFLAGS = $(AM_CFLAGS) -std=gnu99 -Wall -Werror test_plugin_CPPFLAGS = $(AM_CPPFLAGS) -std=gnu99 -Wall -Werror -I$(top_srcdir)/src -test_plugin_LDADD = $(builddir)/libcin3.a -lnobugmt -lpthread -ldl +test_plugin_LDADD = libcin3.a -lnobugmt -lpthread -ldl test_plugin_SOURCES = $(examples_srcdir)/plugin_main.c noinst_HEADERS += $(examples_srcdir)/hello_interface.h From 9bf36e1eb430f8c659e7dd46f56c31a73974e23c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 16:57:39 +0200 Subject: [PATCH 04/11] Moved function doc from mutex.h to mutex.c --- src/lib/mutex.c | 10 ++++++++++ src/lib/mutex.h | 10 ---------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/lib/mutex.c b/src/lib/mutex.c index be36f58d2..0c38f95ce 100644 --- a/src/lib/mutex.c +++ b/src/lib/mutex.c @@ -21,6 +21,11 @@ #include "lib/mutex.h" +/** + * Initialize a mutex variable + * @param self is a pointer to the mutex to be initialized + * @return self as given + */ CinelerraMutex cinelerra_mutex_init (CinelerraMutex self) { @@ -31,6 +36,11 @@ cinelerra_mutex_init (CinelerraMutex self) return self; } +/** + * Destroy a mutex variable + * @param self is a pointer to the mutex to be destroyed + * @return self as given + */ CinelerraMutex cinelerra_mutex_destroy (CinelerraMutex self) { diff --git a/src/lib/mutex.h b/src/lib/mutex.h index d9a26ef61..32a116f01 100644 --- a/src/lib/mutex.h +++ b/src/lib/mutex.h @@ -36,20 +36,10 @@ typedef struct cinelerra_mutex_struct cinelerra_mutex; typedef cinelerra_mutex* CinelerraMutex; -/** - * Initialize a mutex variable - * @param self is a pointer to the mutex to be initialized - * @return self as given - */ CinelerraMutex cinelerra_mutex_init (CinelerraMutex self); -/** - * Destroy a mutex variable - * @param self is a pointer to the mutex to be destroyed - * @return self as given - */ CinelerraMutex cinelerra_mutex_destroy (CinelerraMutex self); From b67af669ee6fa5f1d2d6c11593db20bdbc0c0bb0 Mon Sep 17 00:00:00 2001 From: Christian Thaeter Date: Sat, 20 Oct 2007 17:00:53 +0200 Subject: [PATCH 05/11] removed check for list=!NULL which barfs on gcc 4.2 --- src/lib/llist.h | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/lib/llist.h b/src/lib/llist.h index 4480e507b..032210a35 100644 --- a/src/lib/llist.h +++ b/src/lib/llist.h @@ -115,7 +115,6 @@ typedef llist ** LList_ref; * @param node pointer to the iterated node */ #define LLIST_FOREACH(list, node) \ - if (!list); else \ for (LList node = llist_head (list); \ ! llist_is_end (node, list); \ llist_forward (&node)) @@ -126,7 +125,6 @@ typedef llist ** LList_ref; * @param node pointer to the iterated node */ #define LLIST_FOREACH_REV(list, node) \ - if (!list); else \ for (LList node = llist_tail (list); \ ! llist_is_end (node, list); \ llist_backward (&node)) @@ -138,7 +136,6 @@ typedef llist ** LList_ref; * @param head pointer to the head node */ #define LLIST_WHILE_HEAD(list, head) \ - if (!list); else \ for (LList head = llist_head (list); \ !llist_is_empty (list); \ head = llist_head (list)) @@ -150,7 +147,6 @@ typedef llist ** LList_ref; * @param tail pointer to the tail node */ #define LLIST_WHILE_TAIL(list, tail) \ - if (!list); else \ for (LList tail = llist_tail (list); \ !llist_is_empty (list); \ tail = llist_tail (list)) From e628110d45f30907f33538ae6e14c5340df098b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 17:03:59 +0200 Subject: [PATCH 06/11] Moved function doc from plugin.h to plugin.c --- src/lib/plugin.c | 19 +++++++++++++++++++ src/lib/plugin.h | 18 ------------------ 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/src/lib/plugin.c b/src/lib/plugin.c index 4005bb204..062e266b5 100644 --- a/src/lib/plugin.c +++ b/src/lib/plugin.c @@ -100,6 +100,10 @@ cinelerra_plugin_name_cmp (const void* a, const void* b) return strcmp (((struct cinelerra_plugin*) a)->name, ((struct cinelerra_plugin*) b)->name); } +/** + * Initialize the plugin system. + * always succeeds or aborts + */ void cinelerra_init_plugin (void) { @@ -149,6 +153,16 @@ cinelerra_plugin_lookup (struct cinelerra_plugin* self, const char* path) return -1; /* plugin not found */ } + +/** + * Make an interface available. + * To use an interface provided by a plugin it must be opened first. It is allowed to open an interface more than once. + * Each open must be paired with a close. + * @param plugin name of the plugin to use. + * @param name name of the interface to open. + * @param min_revision the size of the interface structure is used as measure of a minimal required revision (new functions are appended at the end) + * @return handle to the interface or NULL in case of a error. The application shall cast this handle to the actual interface type. + */ struct cinelerra_interface* cinelerra_interface_open (const char* name, const char* interface, size_t min_revision) { @@ -277,6 +291,11 @@ cinelerra_interface_open (const char* name, const char* interface, size_t min_re return NULL; } +/** + * Close an interface. Does not free associated resources + * Calling this function with self==NULL is legal. Every interface handle must be closed only once. + * @param self interface to be closed + */ void cinelerra_interface_close (void* ptr) { diff --git a/src/lib/plugin.h b/src/lib/plugin.h index b787870d2..a710c8285 100644 --- a/src/lib/plugin.h +++ b/src/lib/plugin.h @@ -90,32 +90,14 @@ struct cinelerra_interface int (*close)(void); }; -/** - * Initialize the plugin system. - * always succeeds or aborts - */ void cinelerra_init_plugin (void); -/** - * Make an interface available. - * To use an interface provided by a plugin it must be opened first. It is allowed to open an interface more than once. - * Each open must be paired with a close. - * @param plugin name of the plugin to use. - * @param name name of the interface to open. - * @param min_revision the size of the interface structure is used as measure of a minimal required revision (new functions are appended at the end) - * @return handle to the interface or NULL in case of a error. The application shall cast this handle to the actual interface type. - */ struct cinelerra_interface* cinelerra_interface_open (const char* plugin, const char* name, size_t min_revision); -/** - * Close an interface. Does not free associated resources - * Calling this function with self==NULL is legal. Every interface handle must be closed only once. - * @param self interface to be closed - */ void cinelerra_interface_close (void* self); From d9c9b4e15e2ecbf06c5ba74398c2d5cac37270af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 17:08:12 +0200 Subject: [PATCH 07/11] Moved function doc from rwlock.h to rwlock.c --- src/lib/rwlock.c | 29 +++++++++++++++++++++++++++++ src/lib/rwlock.h | 29 ----------------------------- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/src/lib/rwlock.c b/src/lib/rwlock.c index 018c69f63..d59b8c2d2 100644 --- a/src/lib/rwlock.c +++ b/src/lib/rwlock.c @@ -27,6 +27,11 @@ CINELERRA_ERROR_DEFINE(RWLOCK_AGAIN, "maximum number of readlocks exceed"); CINELERRA_ERROR_DEFINE(RWLOCK_DEADLOCK, "deadlock detected"); +/** + * Initialize a rwlock + * @param self is a pointer to the rwlock to be initialized + * @return self as given + */ CinelerraRWLock cinelerra_rwlock_init (CinelerraRWLock self) { @@ -37,6 +42,11 @@ cinelerra_rwlock_init (CinelerraRWLock self) return self; } +/** + * destroy a rwlock + * @param self is a pointer to the rwlock to be initialized + * @return self on success or NULL at error + */ CinelerraRWLock cinelerra_rwlock_destroy (CinelerraRWLock self) { @@ -51,6 +61,13 @@ cinelerra_rwlock_destroy (CinelerraRWLock self) +/** + * initialize a rwlockacquirer state + * @param self rwlockacquirer to be initialized, must be an automatic variable + * @param cond associated rwlock + * @param state initial state of the mutex, either CINELERRA_RDLOCKED, CINELERRA_WRLOCKED or CINELERRA_UNLOCKED + * @return self as given or NULL on error + */ CinelerraRWLockacquirer cinelerra_rwlockacquirer_init (CinelerraRWLockacquirer self, CinelerraRWLock rwlock, enum cinelerra_lockstate state) { @@ -94,6 +111,12 @@ cinelerra_rwlockacquirer_init (CinelerraRWLockacquirer self, CinelerraRWLock rwl } +/** + * readlock the rwlock. + * must not already be locked + * @param self rwlockacquirer associated with a rwlock + * @return self as given or NULL on error + */ CinelerraRWLockacquirer cinelerra_rwlockacquirer_rdlock (CinelerraRWLockacquirer self) { @@ -119,6 +142,12 @@ cinelerra_rwlockacquirer_rdlock (CinelerraRWLockacquirer self) } +/** + * writelock the rwlock. + * must not already be locked + * @param self rwlockacquirer associated with a rwlock + * @return self as given or NULL on error + */ CinelerraRWLockacquirer cinelerra_rwlockacquirer_wrlock (CinelerraRWLockacquirer self) { diff --git a/src/lib/rwlock.h b/src/lib/rwlock.h index 9bc07f9f3..c7cc7ed16 100644 --- a/src/lib/rwlock.h +++ b/src/lib/rwlock.h @@ -47,20 +47,10 @@ typedef struct cinelerra_rwlock_struct cinelerra_rwlock; typedef cinelerra_rwlock* CinelerraRWLock; -/** - * Initialize a rwlock - * @param self is a pointer to the rwlock to be initialized - * @return self as given - */ CinelerraRWLock cinelerra_rwlock_init (CinelerraRWLock self); -/** - * destroy a rwlock - * @param self is a pointer to the rwlock to be initialized - * @return self on success or NULL at error - */ CinelerraRWLock cinelerra_rwlock_destroy (CinelerraRWLock self); @@ -90,32 +80,13 @@ cinelerra_rwlockacquirer_ensureunlocked (CinelerraRWLockacquirer self) cinelerra_rwlockacquirer NOBUG_CLEANUP(cinelerra_rwlockacquirer_ensureunlocked) -/** - * initialize a rwlockacquirer state - * @param self rwlockacquirer to be initialized, must be an automatic variable - * @param cond associated rwlock - * @param state initial state of the mutex, either CINELERRA_RDLOCKED, CINELERRA_WRLOCKED or CINELERRA_UNLOCKED - * @return self as given or NULL on error - */ CinelerraRWLockacquirer cinelerra_rwlockacquirer_init (CinelerraRWLockacquirer self, CinelerraRWLock rwlock, enum cinelerra_lockstate state); -/** - * readlock the rwlock. - * must not already be locked - * @param self rwlockacquirer associated with a rwlock - * @return self as given or NULL on error - */ CinelerraRWLockacquirer cinelerra_rwlockacquirer_rdlock (CinelerraRWLockacquirer self); -/** - * writelock the rwlock. - * must not already be locked - * @param self rwlockacquirer associated with a rwlock - * @return self as given or NULL on error - */ CinelerraRWLockacquirer cinelerra_rwlockacquirer_wrlock (CinelerraRWLockacquirer self); From 74a7bf449343f1d33b9d1bcf8cd59f5b0dfaf09d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 17:27:27 +0200 Subject: [PATCH 08/11] Made a @file-skeleton for doxygen for the files in src/lib/ --- src/lib/condition.c | 3 +++ src/lib/condition.h | 4 ++++ src/lib/error.c | 5 +++++ src/lib/error.h | 2 +- src/lib/framerate.c | 5 +++++ src/lib/framerate.h | 5 +++++ src/lib/locking.h | 4 ++++ src/lib/mutex.c | 5 +++++ src/lib/mutex.h | 5 +++++ src/lib/plugin.c | 5 +++++ src/lib/plugin.h | 5 +++++ src/lib/references.h | 5 +++++ src/lib/rwlock.c | 4 ++++ src/lib/rwlock.h | 4 ++++ src/lib/time.h | 1 + 15 files changed, 61 insertions(+), 1 deletion(-) diff --git a/src/lib/condition.c b/src/lib/condition.c index 795cd121e..dfc79c7c5 100644 --- a/src/lib/condition.c +++ b/src/lib/condition.c @@ -21,6 +21,9 @@ #include "lib/condition.h" +/** + * @file Condition variables + */ /** * Initialize a condition variable diff --git a/src/lib/condition.h b/src/lib/condition.h index 67e8175e7..7925fd993 100644 --- a/src/lib/condition.h +++ b/src/lib/condition.h @@ -24,6 +24,10 @@ #include "lib/locking.h" +/** + * @file Condition variables, header + */ + /** * Condition variables. diff --git a/src/lib/error.c b/src/lib/error.c index 910db3984..49756c614 100644 --- a/src/lib/error.c +++ b/src/lib/error.c @@ -23,6 +23,11 @@ #include "lib/error.h" +/** + * @file C Error handling in Cinelerra. + */ + + /* predefined errors */ diff --git a/src/lib/error.h b/src/lib/error.h index 21d9dcb73..2b5051652 100644 --- a/src/lib/error.h +++ b/src/lib/error.h @@ -31,7 +31,7 @@ extern "C" { #include /** - * C Error handling in Cinelerra. + * @file C Error handling in Cinelerra, header. */ diff --git a/src/lib/framerate.c b/src/lib/framerate.c index 138a338a3..b70121a37 100644 --- a/src/lib/framerate.c +++ b/src/lib/framerate.c @@ -21,5 +21,10 @@ #include "lib/error.h" +/** + * @file Framerate calculations. + */ + + CINELERRA_ERROR_DEFINE(FRAMERATE_ILLEGAL_TIME, "invalid time given"); CINELERRA_ERROR_DEFINE(FRAMERATE_ILLEGAL_FRAME, "invalid frame given"); diff --git a/src/lib/framerate.h b/src/lib/framerate.h index 2df5971fb..1e862ed0d 100644 --- a/src/lib/framerate.h +++ b/src/lib/framerate.h @@ -27,6 +27,11 @@ #include "lib/error.h" #include "lib/time.h" +/** + * @file Framerate calculations, header. + */ + + /** * framerates are defined as a rational number * for example NTSC with 30000/1001fps diff --git a/src/lib/locking.h b/src/lib/locking.h index fce854b0d..6e53fee97 100644 --- a/src/lib/locking.h +++ b/src/lib/locking.h @@ -28,6 +28,10 @@ #include "lib/error.h" +/** + * @file Shared declarations for all locking primitives. + */ + /** * used to store the current lock state. * diff --git a/src/lib/mutex.c b/src/lib/mutex.c index 0c38f95ce..1425fdd02 100644 --- a/src/lib/mutex.c +++ b/src/lib/mutex.c @@ -21,6 +21,11 @@ #include "lib/mutex.h" +/** + * @file Mutual exclusion locking. + */ + + /** * Initialize a mutex variable * @param self is a pointer to the mutex to be initialized diff --git a/src/lib/mutex.h b/src/lib/mutex.h index 32a116f01..a359d9b75 100644 --- a/src/lib/mutex.h +++ b/src/lib/mutex.h @@ -24,6 +24,11 @@ #include "lib/locking.h" +/** + * @file Mutual exclusion locking, header. + */ + + /** * Mutex. * diff --git a/src/lib/plugin.c b/src/lib/plugin.c index 062e266b5..f71eab529 100644 --- a/src/lib/plugin.c +++ b/src/lib/plugin.c @@ -28,6 +28,11 @@ #include "plugin.h" +/** + * @file Plugin loader. + */ + + /* TODO should be set by the build system to the actual plugin path */ #define CINELERRA_PLUGIN_PATH "~/.cinelerra3/plugins:/usr/local/lib/cinelerra3/plugins:.libs" diff --git a/src/lib/plugin.h b/src/lib/plugin.h index a710c8285..a31e69199 100644 --- a/src/lib/plugin.h +++ b/src/lib/plugin.h @@ -32,6 +32,11 @@ extern "C" { #include "error.h" +/** + * @file Plugin loader, header. + */ + + NOBUG_DECLARE_FLAG (cinelerra_plugin); /* tool macros*/ diff --git a/src/lib/references.h b/src/lib/references.h index dd5988ec7..5f5543787 100644 --- a/src/lib/references.h +++ b/src/lib/references.h @@ -24,6 +24,11 @@ #include +/** + * @file Strong and Weak references, header. + */ + + typedef struct cinelerra_reference_struct cinelerra_reference; typedef cinelerra_reference* CinelerraReference; diff --git a/src/lib/rwlock.c b/src/lib/rwlock.c index d59b8c2d2..a2de75be8 100644 --- a/src/lib/rwlock.c +++ b/src/lib/rwlock.c @@ -26,6 +26,10 @@ CINELERRA_ERROR_DEFINE(RWLOCK_AGAIN, "maximum number of readlocks exceed"); CINELERRA_ERROR_DEFINE(RWLOCK_DEADLOCK, "deadlock detected"); +/** + * @file Read/write locks. + */ + /** * Initialize a rwlock diff --git a/src/lib/rwlock.h b/src/lib/rwlock.h index c7cc7ed16..21ad1e054 100644 --- a/src/lib/rwlock.h +++ b/src/lib/rwlock.h @@ -34,6 +34,10 @@ CINELERRA_ERROR_DECLARE(RWLOCK_AGAIN); CINELERRA_ERROR_DECLARE(RWLOCK_DEADLOCK); +/** + * @file Read/write locks, header. + */ + /** * RWLock. diff --git a/src/lib/time.h b/src/lib/time.h index a2dea483b..34c0035e4 100644 --- a/src/lib/time.h +++ b/src/lib/time.h @@ -29,6 +29,7 @@ #include "lib/error.h" /* + * @file Time calculations. this time functions are small macro like wrapers, they are all inlined for performance reasons time is passed around as pointers, this pointer must never be NULL From 8afd4e1b8d5550d450bc18faaafc5ecb65cc0de6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 17:38:03 +0200 Subject: [PATCH 09/11] Documented cinelerra_plugin_lookup in plugin.c --- src/lib/plugin.c | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/lib/plugin.c b/src/lib/plugin.c index f71eab529..c37e8fec3 100644 --- a/src/lib/plugin.c +++ b/src/lib/plugin.c @@ -115,6 +115,14 @@ cinelerra_init_plugin (void) NOBUG_INIT_FLAG (cinelerra_plugin); } +/** + * Find and set pathname for the plugin. + * Searches through given path for given plugin, trying to find the file's location in the filesystem. + * If found, self->pathname will be set to the found plugin file. + * @param self The cinelerra_plugin to open look for. + * @param path The path to search trough (paths seperated by ":") + * @return 0 on success. -1 on error, or if plugin not found in path. + */ int cinelerra_plugin_lookup (struct cinelerra_plugin* self, const char* path) { From 9952aa33a483d352e45bc205ce78563be30a0cda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 17:50:42 +0200 Subject: [PATCH 10/11] Updated function docs to use the actual variables and cut textwidth at 105 --- src/lib/error.c | 8 +++++--- src/lib/plugin.c | 21 +++++++++++++-------- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/src/lib/error.c b/src/lib/error.c index 49756c614..d5ea88f01 100644 --- a/src/lib/error.c +++ b/src/lib/error.c @@ -47,8 +47,9 @@ cinelerra_error_tls_init (void) /** * Set error state for the current thread. * If the error state of the current thread was cleared, then set it, else preserve the old state. - * @param err name of the error with 'CINELERRA_ERROR_' prefix (example: CINELERRA_ERROR_NO_MEMORY) - * @return old state, that is NULL for success, when the state was cleared and a pointer to a pending error when the error state was already set + * @param nerr name of the error with 'CINELERRA_ERROR_' prefix (example: CINELERRA_ERROR_NO_MEMORY) + * @return old state, that is NULL for success, when the state was cleared and a pointer to a pending + * error when the error state was already set */ const char* cinelerra_error_set (const char * nerr) @@ -65,7 +66,8 @@ cinelerra_error_set (const char * nerr) /** * Get and clear current error state. - * This function clears the error state, if it needs to be reused, one has to store it in a temporary variable. + * This function clears the error state, if it needs to be reused, one has to store it in a temporary + * variable. * @return pointer to any pending error of this thread, NULL if no error is pending */ const char* diff --git a/src/lib/plugin.c b/src/lib/plugin.c index c37e8fec3..184b0cb06 100644 --- a/src/lib/plugin.c +++ b/src/lib/plugin.c @@ -98,7 +98,10 @@ void* cinelerra_plugin_registry = NULL; /* plugin operations are protected by one big mutex */ pthread_mutex_t cinelerra_plugin_mutex = PTHREAD_MUTEX_INITIALIZER; -/* the compare function for the registry tree */ +/** + * the compare function for the registry tree. + * Compares the names of two struct cinelerra_plugin. + * @return 0 if a and b are equal, just like strcmp. */ static int cinelerra_plugin_name_cmp (const void* a, const void* b) { @@ -169,12 +172,14 @@ cinelerra_plugin_lookup (struct cinelerra_plugin* self, const char* path) /** * Make an interface available. - * To use an interface provided by a plugin it must be opened first. It is allowed to open an interface more than once. - * Each open must be paired with a close. - * @param plugin name of the plugin to use. - * @param name name of the interface to open. - * @param min_revision the size of the interface structure is used as measure of a minimal required revision (new functions are appended at the end) - * @return handle to the interface or NULL in case of a error. The application shall cast this handle to the actual interface type. + * To use an interface provided by a plugin it must be opened first. It is allowed to open an interface + * more than once. Each open must be paired with a close. + * @param name name of the plugin to use. + * @param interface name of the interface to open. + * @param min_revision the size of the interface structure is used as measure of a minimal required + * revision (new functions are appended at the end) + * @return handle to the interface or NULL in case of a error. The application shall cast this handle to + * the actual interface type. */ struct cinelerra_interface* cinelerra_interface_open (const char* name, const char* interface, size_t min_revision) @@ -307,7 +312,7 @@ cinelerra_interface_open (const char* name, const char* interface, size_t min_re /** * Close an interface. Does not free associated resources * Calling this function with self==NULL is legal. Every interface handle must be closed only once. - * @param self interface to be closed + * @param ptr interface to be closed */ void cinelerra_interface_close (void* ptr) From c2f5665e5657e4efec1a64551e6f60e88cc2fbfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= Date: Sat, 20 Oct 2007 18:10:35 +0200 Subject: [PATCH 11/11] More doxygen documenting in src/lib/. Some name fixes, some new docs. --- src/lib/rwlock.c | 2 +- src/lib/time.h | 35 +++++++++++++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/src/lib/rwlock.c b/src/lib/rwlock.c index a2de75be8..48becb14d 100644 --- a/src/lib/rwlock.c +++ b/src/lib/rwlock.c @@ -68,7 +68,7 @@ cinelerra_rwlock_destroy (CinelerraRWLock self) /** * initialize a rwlockacquirer state * @param self rwlockacquirer to be initialized, must be an automatic variable - * @param cond associated rwlock + * @param rwlock associated rwlock * @param state initial state of the mutex, either CINELERRA_RDLOCKED, CINELERRA_WRLOCKED or CINELERRA_UNLOCKED * @return self as given or NULL on error */ diff --git a/src/lib/time.h b/src/lib/time.h index 34c0035e4..4203ece49 100644 --- a/src/lib/time.h +++ b/src/lib/time.h @@ -31,9 +31,13 @@ /* * @file Time calculations. this time functions are small macro like wrapers, they are all inlined for performance reasons - time is passed around as pointers, this pointer must never be NULL + time is passed around as pointers, this pointer must never be NULL. - timehandling is a delicate business, be careful of precision errors accumulating, TODO explain how to use time + timehandling is a delicate business, be careful of precision errors accumulating + + cinelerra_time is starting from zero, never becomes negative. + + TODO explain how to use time */ @@ -68,6 +72,8 @@ cinelerra_time_normalize (CinelerraTime time) /** * set a time value to zero. + * @param time Time to clear + * @return time as given */ static inline CinelerraTime cinelerra_time_clear (CinelerraTime time) @@ -82,6 +88,8 @@ cinelerra_time_clear (CinelerraTime time) /** * get current time. + * @param time Time to put current time into. + * @return time as given */ static inline CinelerraTime cinelerra_time_current (CinelerraTime time) @@ -97,6 +105,10 @@ cinelerra_time_current (CinelerraTime time) /** * init from floating point representation. + * @param time The time to be set + * @param fp Time in double + * @return time as given upon success, NULL if double time given was negative or given time didn't point + * anywhere */ static inline CinelerraTime cinelerra_time_set_double (CinelerraTime time, double fp) @@ -121,6 +133,10 @@ cinelerra_time_set_double (CinelerraTime time, double fp) /** * initialize with seconds and microseconds. + * @param time Time to set + * @param sec Seconds to set + * @param usec Microseconds to set + * @param Time as given */ static inline CinelerraTime cinelerra_time_init (CinelerraTime time, time_t sec, suseconds_t usec) @@ -136,6 +152,8 @@ cinelerra_time_init (CinelerraTime time, time_t sec, suseconds_t usec) /** * get the seconds part from a time. + * @param time Time to get seconds from + * @return Seconds elapsed, -1 on error */ static inline time_t cinelerra_time_sec (CinelerraTime time) @@ -148,6 +166,8 @@ cinelerra_time_sec (CinelerraTime time) /** * get the microseconds part of a time. + * @param time Time to get microseconds from + * @return Microseconds elapsed, -1 on error */ static inline suseconds_t cinelerra_time_usec (CinelerraTime time) @@ -160,6 +180,8 @@ cinelerra_time_usec (CinelerraTime time) /** * convert to floating point repesentation. + * @param time Time to get floating point representation from + * @return Floating point representation of time. NAN on error. */ static inline double cinelerra_time_double_get (CinelerraTime time) @@ -178,6 +200,9 @@ cinelerra_time_double_get (CinelerraTime time) /** * copy time + * @param dest Time-pointer to copy to + * @param src Time-source to copy from + * @return dest as given */ static inline CinelerraTime cinelerra_time_copy (CinelerraTime dest, const CinelerraTime src) @@ -192,6 +217,9 @@ cinelerra_time_copy (CinelerraTime dest, const CinelerraTime src) /** * add time. + * @param dest The result of the add + * @param src Time to add to dest + * @return dest as given, or NULL on overflow. */ static inline CinelerraTime cinelerra_time_add (CinelerraTime dest, const CinelerraTime src) @@ -216,6 +244,9 @@ cinelerra_time_add (CinelerraTime dest, const CinelerraTime src) /** * substact time. + * @param dest The result of subtract + * @param src Time to subtract from dest + * @return dest as given, or NULL on underflow. */ static inline CinelerraTime cinelerra_time_sub (CinelerraTime dest, const CinelerraTime src)