From 3ee98f3bac24fd1c70a9de3e0fbe774e762c25b3 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Fri, 26 Jun 2009 15:31:34 +0000 Subject: Add lots of comments, and some code fixes discovered in the process. --- libdimension/dimension/array.h | 14 ++++++++------ libdimension/dimension/camera.h | 7 +++---- libdimension/dimension/canvas.h | 7 ++++--- libdimension/dimension/color.h | 6 +++--- libdimension/dimension/cube.h | 6 +++--- libdimension/dimension/error.h | 19 +++++++++++-------- libdimension/dimension/geometry.h | 4 ++-- libdimension/dimension/object.h | 7 ++++--- libdimension/dimension/png.h | 4 ++++ libdimension/dimension/progress.h | 14 +++++++++++++- libdimension/dimension/raytrace.h | 4 ++++ libdimension/dimension/scene.h | 6 +++--- libdimension/dimension/sphere.h | 6 +++--- 13 files changed, 65 insertions(+), 39 deletions(-) (limited to 'libdimension/dimension') diff --git a/libdimension/dimension/array.h b/libdimension/dimension/array.h index d0693fc..0af4406 100644 --- a/libdimension/dimension/array.h +++ b/libdimension/dimension/array.h @@ -18,14 +18,14 @@ * . * *************************************************************************/ -#ifndef DIMENSION_ARRAY_H -#define DIMENSION_ARRAY_H - /* * Simple thread-safe generalized arrays, for returning variable-length arrays * from functions, and other fun stuff. */ +#ifndef DIMENSION_ARRAY_H +#define DIMENSION_ARRAY_H + #include /* For pthread_rwlock_t */ #include /* For size_t */ @@ -37,24 +37,26 @@ typedef struct { pthread_rwlock_t *rwlock; } dmnsn_array; +/* Array allocation never returns NULL - if dmnsn_new_array, it succeeded */ dmnsn_array *dmnsn_new_array(size_t obj_size); void dmnsn_delete_array(dmnsn_array *array); +/* Thread-safe atomic array access */ + void dmnsn_array_push(dmnsn_array *array, const void *obj); void dmnsn_array_pop(dmnsn_array *array, void *obj); - void dmnsn_array_get(const dmnsn_array *array, size_t i, void *obj); void dmnsn_array_set(dmnsn_array *array, size_t i, const void *obj); size_t dmnsn_array_size(const dmnsn_array *array); void dmnsn_array_resize(dmnsn_array *array, size_t length); -/* Manual locking */ - +/* Non-atomic operations for manual locking */ void *dmnsn_array_at(dmnsn_array *array, size_t i); size_t dmnsn_array_size_unlocked(const dmnsn_array *array); void dmnsn_array_resize_unlocked(dmnsn_array *array, size_t length); +/* Manual locking */ void dmnsn_array_rdlock(const dmnsn_array *array); void dmnsn_array_wrlock(dmnsn_array *array); void dmnsn_array_unlock(const dmnsn_array *array); diff --git a/libdimension/dimension/camera.h b/libdimension/dimension/camera.h index 95b36fa..9b06359 100644 --- a/libdimension/dimension/camera.h +++ b/libdimension/dimension/camera.h @@ -18,13 +18,13 @@ * . * *************************************************************************/ -#ifndef DIMENSION_CAMERA_H -#define DIMENSION_CAMERA_H - /* * A camera. */ +#ifndef DIMENSION_CAMERA_H +#define DIMENSION_CAMERA_H + /* Forward-declare dmnsn_camera */ typedef struct dmnsn_camera dmnsn_camera; @@ -47,7 +47,6 @@ void dmnsn_delete_camera(dmnsn_camera *camera); /* A perspective camera, at the origin, looking at (0, 0, 1). The feild of view is the section of the plane z = 1 from (-0.5, -0.5) to (0.5, 0.5). Rays are transformed by the transformation matrix `trans'. */ - dmnsn_camera *dmnsn_new_perspective_camera(dmnsn_matrix trans); void dmnsn_delete_perspective_camera(dmnsn_camera *camera); diff --git a/libdimension/dimension/canvas.h b/libdimension/dimension/canvas.h index f05264b..50cc612 100644 --- a/libdimension/dimension/canvas.h +++ b/libdimension/dimension/canvas.h @@ -18,14 +18,15 @@ * . * *************************************************************************/ +/* + * A canvas which is rendered to. + */ + #ifndef DIMENSION_CANVAS_H #define DIMENSION_CANVAS_H #include -/* - * A canvas which is rendered to. - */ typedef struct { unsigned int x, y; diff --git a/libdimension/dimension/color.h b/libdimension/dimension/color.h index ab6efa3..f1964c3 100644 --- a/libdimension/dimension/color.h +++ b/libdimension/dimension/color.h @@ -18,13 +18,13 @@ * . * *************************************************************************/ -#ifndef DIMENSION_COLOR_H -#define DIMENSION_COLOR_H - /* * Types to represent color. */ +#ifndef DIMENSION_COLOR_H +#define DIMENSION_COLOR_H + /* Internally, we use CIE 1931 XYZ color. */ typedef struct { double X, Y, Z; diff --git a/libdimension/dimension/cube.h b/libdimension/dimension/cube.h index e7f2b90..e55ec74 100644 --- a/libdimension/dimension/cube.h +++ b/libdimension/dimension/cube.h @@ -18,13 +18,13 @@ * . * *************************************************************************/ -#ifndef DIMENSION_CUBE_H -#define DIMENSION_CUBE_H - /* * A cube, axis-aligned, from (-1, -1, -1) to (1, 1, 1) */ +#ifndef DIMENSION_CUBE_H +#define DIMENSION_CUBE_H + dmnsn_object *dmnsn_new_cube(); void dmnsn_delete_cube(dmnsn_object *cube); diff --git a/libdimension/dimension/error.h b/libdimension/dimension/error.h index 3204cb2..cd7dd81 100644 --- a/libdimension/dimension/error.h +++ b/libdimension/dimension/error.h @@ -18,23 +18,26 @@ * . * *************************************************************************/ -#ifndef DIMENSION_ERROR_H -#define DIMENSION_ERROR_H - /* - * Error handling. + * Error handling. Errors are reported at a given severity by the dmnsn_error() + * macro at a given severity, which prints a warning if it is below the set + * resilience, or prints an error and exits if it's at or above the set + * resilience. */ +#ifndef DIMENSION_ERROR_H +#define DIMENSION_ERROR_H + typedef enum { DMNSN_SEVERITY_LOW, /* Only die on low resilience */ DMNSN_SEVERITY_MEDIUM, /* Die on low or medium resilience */ DMNSN_SEVERITY_HIGH /* Always die */ } dmnsn_severity; -/* Use this to report an error */ -#define dmnsn_error(severity, str) \ - dmnsn_report_error((dmnsn_severity)severity, __PRETTY_FUNCTION__, __LINE__, \ - str) +/* Use this macro to report an error */ +#define dmnsn_error(severity, str) \ + dmnsn_report_error((dmnsn_severity)(severity), __PRETTY_FUNCTION__, __LINE__,\ + (str)) /* Called by dmnsn_error() - don't call directly */ void dmnsn_report_error(dmnsn_severity severity, diff --git a/libdimension/dimension/geometry.h b/libdimension/dimension/geometry.h index 95692c6..c635fd9 100644 --- a/libdimension/dimension/geometry.h +++ b/libdimension/dimension/geometry.h @@ -19,7 +19,7 @@ *************************************************************************/ /* - * Core geometric types like scalars, vectors, and rays. + * Core geometric types like vectors, matricies, and rays. */ #ifndef DIMENSION_GEOMETRY_H @@ -73,6 +73,6 @@ dmnsn_line dmnsn_matrix_line_mul(dmnsn_matrix lhs, dmnsn_line rhs); /* A point on a line, defined by x0 + t*n */ dmnsn_vector dmnsn_line_point(dmnsn_line l, double t); /* Solve for the t value such that x0 + t*n = x */ -double dmnsn_line_index(dmnsn_line l, dmnsn_vector x); +double dmnsn_line_index(dmnsn_line l, dmnsn_vector x); #endif /* DIMENSION_GEOMETRY_H */ diff --git a/libdimension/dimension/object.h b/libdimension/dimension/object.h index 589ac29..d18f426 100644 --- a/libdimension/dimension/object.h +++ b/libdimension/dimension/object.h @@ -18,13 +18,13 @@ * . * *************************************************************************/ -#ifndef DIMENSION_OBJECT_H -#define DIMENSION_OBJECT_H - /* * Objects. */ +#ifndef DIMENSION_OBJECT_H +#define DIMENSION_OBJECT_H + /* Forward-declare dmnsn_object */ typedef struct dmnsn_object dmnsn_object; @@ -46,6 +46,7 @@ struct dmnsn_object { dmnsn_object_inside_fn *inside_fn; }; +/* Allocate a dummy object */ dmnsn_object *dmnsn_new_object(); void dmnsn_delete_object(dmnsn_object *object); diff --git a/libdimension/dimension/png.h b/libdimension/dimension/png.h index 05ff79a..858f79f 100644 --- a/libdimension/dimension/png.h +++ b/libdimension/dimension/png.h @@ -18,6 +18,10 @@ * . * *************************************************************************/ +/* + * Support for exporting/importing canvases to/from PNG files + */ + #ifndef DIMENSION_PNG_H #define DIMENSION_PNG_H diff --git a/libdimension/dimension/progress.h b/libdimension/dimension/progress.h index a865c8f..7958ab9 100644 --- a/libdimension/dimension/progress.h +++ b/libdimension/dimension/progress.h @@ -18,6 +18,13 @@ * . * *************************************************************************/ +/* + * An interface for asynchronous tasks. *_async() versions of functions + * return a dmnsn_progress* object which can indicate the progress of the + * background task, and wait for task completion. The task's return value + * is returned as an int from dmnsn_finish_progress(). + */ + #ifndef DIMENSION_PROGRESS_H #define DIMENSION_PROGRESS_H @@ -43,6 +50,7 @@ typedef struct { } dmnsn_progress; dmnsn_progress *dmnsn_new_progress(); +/* For failed returns from *_async() functions */ void dmnsn_delete_progress(dmnsn_progress *progress); /* This joins the worker thread and returns it's integer return value in @@ -50,10 +58,14 @@ void dmnsn_delete_progress(dmnsn_progress *progress); int dmnsn_finish_progress(dmnsn_progress *progress); double dmnsn_get_progress(const dmnsn_progress *progress); +/* Wait for the progress to be >= prog, in a better way than spinlocking */ void dmnsn_wait_progress(const dmnsn_progress *progress, double prog); +/* Create a new level of loop nesting */ void dmnsn_new_progress_element(dmnsn_progress *progress, unsigned int total); +/* Increment the progress counter; should only be called from innermost loop */ void dmnsn_increment_progress(dmnsn_progress *progress); -void dmnsn_progress_done(dmnsn_progress *progress); +/* Instantly complete the progress */ +void dmnsn_done_progress(dmnsn_progress *progress); #endif /* DIMENSION_PROGRESS_H */ diff --git a/libdimension/dimension/raytrace.h b/libdimension/dimension/raytrace.h index a69bb72..b58a39b 100644 --- a/libdimension/dimension/raytrace.h +++ b/libdimension/dimension/raytrace.h @@ -18,6 +18,10 @@ * . * *************************************************************************/ +/* + * Render a scene by raytracing + */ + #ifndef DIMENSION_RAYTRACE_H #define DIMENSION_RAYTRACE_H diff --git a/libdimension/dimension/scene.h b/libdimension/dimension/scene.h index a6f2e5d..35087a7 100644 --- a/libdimension/dimension/scene.h +++ b/libdimension/dimension/scene.h @@ -18,13 +18,13 @@ * . * *************************************************************************/ -#ifndef DIMENSION_SCENE_H -#define DIMENSION_SCENE_H - /* * A scene. */ +#ifndef DIMENSION_SCENE_H +#define DIMENSION_SCENE_H + typedef struct { dmnsn_color background; dmnsn_array *objects; diff --git a/libdimension/dimension/sphere.h b/libdimension/dimension/sphere.h index 2547965..d7a8f54 100644 --- a/libdimension/dimension/sphere.h +++ b/libdimension/dimension/sphere.h @@ -18,13 +18,13 @@ * . * *************************************************************************/ -#ifndef DIMENSION_SPHERE_H -#define DIMENSION_SPHERE_H - /* * A sphere object, of radius 1, centered at the origin. */ +#ifndef DIMENSION_SPHERE_H +#define DIMENSION_SPHERE_H + dmnsn_object *dmnsn_new_sphere(); void dmnsn_delete_sphere(dmnsn_object *sphere); -- cgit v1.2.3