summaryrefslogtreecommitdiffstats
path: root/libdimension/dimension/texture.h
diff options
context:
space:
mode:
Diffstat (limited to 'libdimension/dimension/texture.h')
-rw-r--r--libdimension/dimension/texture.h140
1 files changed, 110 insertions, 30 deletions
diff --git a/libdimension/dimension/texture.h b/libdimension/dimension/texture.h
index 5586e24..f582351 100644
--- a/libdimension/dimension/texture.h
+++ b/libdimension/dimension/texture.h
@@ -18,7 +18,8 @@
* <http://www.gnu.org/licenses/>. *
*************************************************************************/
-/*
+/**
+ * @file
* Object textures.
*/
@@ -32,31 +33,55 @@
/* Forward-declare dmnsn_pigment */
typedef struct dmnsn_pigment dmnsn_pigment;
-/* Pigment callbacks */
+/**
+ * Pigment callback.
+ * @param[in] pigment The pigment itself.
+ * @param[in] v The point to color.
+ * @return The color of the pigment at \p v.
+ */
typedef dmnsn_color dmnsn_pigment_fn(const dmnsn_pigment *pigment,
dmnsn_vector v);
+
+/**
+ * Pigment initializer callback.
+ * @param[in,out] pigment The pigment to initialize.
+ */
typedef void dmnsn_pigment_init_fn(dmnsn_pigment *pigment);
-/* dmnsn_pigment definition */
+/** A pigment */
struct dmnsn_pigment {
- /* Callbacks */
- dmnsn_pigment_fn *pigment_fn;
- dmnsn_pigment_init_fn *init_fn;
- dmnsn_free_fn *free_fn;
+ dmnsn_pigment_fn *pigment_fn; /**< The pigment callback. */
+ dmnsn_pigment_init_fn *init_fn; /**< The initializer callback. */
+ dmnsn_free_fn *free_fn; /**< The destructor callback. */
- /* Transformation matrix */
- dmnsn_matrix trans, trans_inv;
+ dmnsn_matrix trans; /**< Transformation matrix. */
+ dmnsn_matrix trans_inv; /**< The inverse of the transformation matrix. */
- /* Quick color */
+ /** Quick color -- used for low-quality renders. */
dmnsn_color quick_color;
- /* Generic pointer */
+ /** Generic pointer */
void *ptr;
};
+/**
+ * Allocate a new dummy pigment.
+ * @return The allocated pigment.
+ */
dmnsn_pigment *dmnsn_new_pigment(void);
+
+/**
+ * Delete a pigment.
+ * @param[in,out] pigment The pigment to delete.
+ */
void dmnsn_delete_pigment(dmnsn_pigment *pigment);
+/**
+ * Initialize a pigment. Pigments should not be used before being initialized,
+ * but should not be modified after being initialized. Pigments are generally
+ * initialized for you.
+ * @param[in,out] pigment The pigment to initialize.
+ */
void dmnsn_pigment_init(dmnsn_pigment *pigment);
/*
@@ -66,56 +91,111 @@ void dmnsn_pigment_init(dmnsn_pigment *pigment);
/* Forward-declare dmnsn_finish */
typedef struct dmnsn_finish dmnsn_finish;
-/* Finish callbacks */
+/**
+ * Diffuse reflection callback.
+ * @param[in] finish The finish itself.
+ * @param[in] light The color of the light illuminating the object.
+ * @param[in] color The pigment of the object.
+ * @param[in] ray The direction of the light source.
+ * @param[in] normal The normal vector of the surface.
+ * @return The diffuse reflection component of the object's color.
+ */
typedef dmnsn_color dmnsn_diffuse_fn(const dmnsn_finish *finish,
dmnsn_color light, dmnsn_color color,
dmnsn_vector ray, dmnsn_vector normal);
+/**
+ * Specular highlight callback.
+ * @param[in] finish The finish itself.
+ * @param[in] light The color of the light illuminating the object.
+ * @param[in] color The pigment of the object.
+ * @param[in] ray The direction of the light source.
+ * @param[in] normal The normal vector of the surface.
+ * @param[in] viewer The direction of the viewer.
+ * @return The specular reflection component of the object's color.
+ */
typedef dmnsn_color dmnsn_specular_fn(const dmnsn_finish *finish,
dmnsn_color light, dmnsn_color color,
dmnsn_vector ray, dmnsn_vector normal,
dmnsn_vector viewer);
+/**
+ * Ambient light callback.
+ * @param[in] finish The finish itself.
+ * @param[in] pigment The pigment of the object.
+ * @return The ambient contribution to the object's color.
+ */
typedef dmnsn_color dmnsn_ambient_fn(const dmnsn_finish *finish,
dmnsn_color pigment);
+/**
+ * Reflected light callback.
+ * @param[in] finish The finish itself.
+ * @param[in] reflect The color of the reflected ray.
+ * @param[in] color The pigment of the object.
+ * @param[in] ray The direction of the reflected ray.
+ * @param[in] normal The normal vector of the surface.
+ * @return The contribution of the reflected ray to the object's color.
+ */
typedef dmnsn_color dmnsn_reflection_fn(const dmnsn_finish *finish,
dmnsn_color reflect, dmnsn_color color,
dmnsn_vector ray, dmnsn_vector normal);
-/* dmnsn_finish definition */
+/** A finish. */
struct dmnsn_finish {
- /* Callbacks */
- dmnsn_diffuse_fn *diffuse_fn;
- dmnsn_specular_fn *specular_fn;
- dmnsn_ambient_fn *ambient_fn;
- dmnsn_reflection_fn *reflection_fn;
- dmnsn_free_fn *free_fn;
-
- /* Generic pointer */
+ dmnsn_diffuse_fn *diffuse_fn; /**< The diffuse callback. */
+ dmnsn_specular_fn *specular_fn; /**< The specular callback. */
+ dmnsn_ambient_fn *ambient_fn; /**< The ambient callback. */
+ dmnsn_reflection_fn *reflection_fn; /**< The reflection callback. */
+ dmnsn_free_fn *free_fn; /**< The destruction callback. */
+
+ /** Generic pointer */
void *ptr;
};
+/**
+ * Allocate a new dummy finish.
+ * @return The allocated finish.
+ */
dmnsn_finish *dmnsn_new_finish(void);
+
+/**
+ * Delete a finish.
+ * @param[in,out] finish The finish to delete.
+ */
void dmnsn_delete_finish(dmnsn_finish *finish);
/*
- * A complete texture
+ * Textures
*/
+/** A complete texture. */
typedef struct {
- /* Texture components */
- dmnsn_pigment *pigment;
- dmnsn_finish *finish;
+ dmnsn_pigment *pigment; /**< Pigment. */
+ dmnsn_finish *finish; /**< Finish. */
- /* Transformation matrix */
- dmnsn_matrix trans, trans_inv;
+ dmnsn_matrix trans; /**< Transformation matrix. */
+ dmnsn_matrix trans_inv; /**< The inverse of the transformation matrix. */
- /* Reference count */
- unsigned int *refcount;
- bool should_init;
+ unsigned int *refcount; /**< @internal Reference count. */
+ bool should_init; /**< @internal Whether to init the texture. */
} dmnsn_texture;
+/**
+ * Create a blank texture.
+ * @return The new texture.
+ */
dmnsn_texture *dmnsn_new_texture(void);
+
+/**
+ * Delete a texture.
+ * @param[in,out] texture The texture to delete.
+ */
void dmnsn_delete_texture(dmnsn_texture *texture);
+/**
+ * Initialize a texture. Textures should not be used before being initialized,
+ * but should not be modified after being initialized. Textures are generally
+ * initialized for you.
+ * @param[in,out] texture The texture to initialize.
+ */
void dmnsn_texture_init(dmnsn_texture *texture);
#endif /* DIMENSION_TEXTURE_H */