summaryrefslogtreecommitdiffstats
path: root/libdimension/dimension/pattern.h
diff options
context:
space:
mode:
Diffstat (limited to 'libdimension/dimension/pattern.h')
-rw-r--r--libdimension/dimension/pattern.h50
1 files changed, 38 insertions, 12 deletions
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 @@
* <http://www.gnu.org/licenses/>. *
*************************************************************************/
-/*
- * 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 */