diff options
Diffstat (limited to 'libdimension/dimension/texture.h')
| -rw-r--r-- | libdimension/dimension/texture.h | 140 |
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 */ |