From 8fe33a340b8979a73fa84f201c15519a9b5d0266 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Sun, 14 Nov 2010 21:20:43 -0500 Subject: Document libdimension with Doxygen. --- libdimension/dimension/pattern.h | 50 ++++++++++++++++++++++++++++++---------- 1 file changed, 38 insertions(+), 12 deletions(-) (limited to 'libdimension/dimension/pattern.h') diff --git a/libdimension/dimension/pattern.h b/libdimension/dimension/pattern.h index 6301372..9636155 100644 --- a/libdimension/dimension/pattern.h +++ b/libdimension/dimension/pattern.h @@ -18,8 +18,10 @@ * . * *************************************************************************/ -/* - * Patterns +/** + * @file + * Patterns. Patterns are functions which map vectors to scalars, which are + * used for pigments and normals. */ #ifndef DIMENSION_PATTERN_H @@ -28,28 +30,52 @@ /* Forward-declare dmnsn_pattern */ typedef struct dmnsn_pattern dmnsn_pattern; -/* Pattern callback */ +/** + * Pattern callback. + * @param[in] pattern The pattern itself. + * @param[in] v The point at which to evaluate the pattern. + * @return The value of the pattern at \p v. + */ typedef double dmnsn_pattern_fn(const dmnsn_pattern *pattern, dmnsn_vector v); -/* Generic pattern */ +/** A pattern. */ struct dmnsn_pattern { - /* Callbacks */ - dmnsn_pattern_fn *pattern_fn; - dmnsn_free_fn *free_fn; + dmnsn_pattern_fn *pattern_fn; /**< The pattern callback. */ + dmnsn_free_fn *free_fn; /**< The destructor callback. */ - /* Transformation matrix */ - dmnsn_matrix trans, trans_inv; + dmnsn_matrix trans; /**< The transformation matrix of the pattern */ + dmnsn_matrix trans_inv; /**< The inverse of the transformation matrix */ - /* Generic pointer */ - void *ptr; + void *ptr; /**< Generic pointer */ }; +/** + * Allocate an dummy pattern. + * @return A pattern with no callbacks set. + */ dmnsn_pattern *dmnsn_new_pattern(void); + +/** + * Delete a pattern. + * @param[in,out] pattern The pattern to destroy. + */ void dmnsn_delete_pattern(dmnsn_pattern *pattern); +/** + * Initialize a pattern. This precomputes some values that are used during + * ray-tracing; the pattern will not work until it has been initialized, but + * should not be modified after it has been initialized. Patterns are generally + * initialized for you. + * @param[in,out] pattern The pattern to initialize. + */ void dmnsn_pattern_init(dmnsn_pattern *pattern); -/* Invoke the pattern callback with the right transformation */ +/** + * Invoke the pattern callback with the right transformation. + * @param[in] pattern The pattern to evaluate. + * @param[in] v The point to get the pattern value for. + * @return The value of the pattern at \p v. + */ double dmnsn_pattern_value(const dmnsn_pattern *pattern, dmnsn_vector v); #endif /* DIMENSION_PATTERN_H */ -- cgit v1.2.3