Progressive surfaces

Name

Progressive surfaces -- continuous level-of-detail for surfaces.

Synopsis


#include <gts.h>


#define     GTS_PSURFACE_CLASS              (klass)
#define     GTS_PSURFACE                    (obj)
#define     GTS_IS_PSURFACE                 (obj)
#define     GTS_PSURFACE_IS_CLOSED          (ps)
struct      GtsPSurfaceClass;
struct      GtsPSurface;
GtsPSurfaceClass* gts_psurface_class        (void);
GtsPSurface* gts_psurface_new               (GtsPSurfaceClass *klass,
                                             GtsSurface *surface,
                                             GtsSplitClass *split_class,
                                             GtsKeyFunc cost_func,
                                             gpointer cost_data,
                                             GtsCoarsenFunc coarsen_func,
                                             gpointer coarsen_data,
                                             GtsStopFunc stop_func,
                                             gpointer stop_data,
                                             gdouble minangle);
GtsSplit*   gts_psurface_add_vertex         (GtsPSurface *ps);
GtsSplit*   gts_psurface_remove_vertex      (GtsPSurface *ps);
void        gts_psurface_set_vertex_number  (GtsPSurface *ps,
                                             guint n);
guint       gts_psurface_get_vertex_number  (GtsPSurface *ps);
guint       gts_psurface_min_vertex_number  (GtsPSurface *ps);
guint       gts_psurface_max_vertex_number  (GtsPSurface *ps);
void        gts_psurface_foreach_vertex     (GtsPSurface *ps,
                                             GtsFunc func,
                                             gpointer data);
GtsPSurface* gts_psurface_open              (GtsPSurfaceClass *klass,
                                             GtsSurface *s,
                                             GtsSplitClass *split_class,
                                             FILE *fptr,
                                             guint *line);
GtsSplit*   gts_psurface_read_vertex        (GtsPSurface *ps,
                                             FILE *fptr);
void        gts_psurface_close              (GtsPSurface *ps);
void        gts_psurface_write              (GtsPSurface *ps,
                                             FILE *fptr);

Description

Progressive surfaces allow you to control precisely and continuously the level of detail of a GtsSurface. They are built off-line by storing the sequence of edge collapses performed during surface simplification (see gts_psurface_new()). Fast traversal of the pre-built sequence allow on-line selection of the required level of detail.

Using the gts_psurface_write() function a text representation of a progressive surface can be written to a file, pipe or socket. This text representation allows the progressive transmission of a surface, starting with the coarsest representation and progressively refining it as data is read or received (see gts_psurface_open(), gts_psurface_read_vertex() and gts_psurface_close() for details).

Details

GTS_PSURFACE_CLASS()

#define     GTS_PSURFACE_CLASS(klass)

Casts klass to GtsPSurfaceClass.

klass :a descendant of GtsPSurfaceClass.


GTS_PSURFACE()

#define     GTS_PSURFACE(obj)

Casts obj to GtsPSurface.

obj :a descendant of GtsPSurface.


GTS_IS_PSURFACE()

#define     GTS_IS_PSURFACE(obj)

Evaluates to TRUE if obj is a GtsPSurface, FALSE otherwise.

obj :a pointer to test.


GTS_PSURFACE_IS_CLOSED()

#define GTS_PSURFACE_IS_CLOSED(ps)  (!(ps)->vertices)

Evaluates to TRUE if ps has not been created with gts_psurface_open() or if it has been closed using gts_psurface_close().

ps :a GtsPSurface.


struct GtsPSurfaceClass

struct GtsPSurfaceClass {
  GtsObjectClass parent_class;
};

The progressive surface class derived from GtsObjectClass.


struct GtsPSurface

struct GtsPSurface {
  GtsObject object;

  GtsSurface * s;
  GPtrArray * split;
  GtsSplitClass * split_class;
  guint pos, min;

  GPtrArray * vertices, * faces;
};

The progressive surface object derived from GtsObject. The field s is the GtsSurface being refined or coarsened by operations on the progressive surface. All the other fields must be considered private and accessed only through the following functions.


gts_psurface_class ()

GtsPSurfaceClass* gts_psurface_class        (void);

Returns : the GtsPSurfaceClass.


gts_psurface_new ()

GtsPSurface* gts_psurface_new               (GtsPSurfaceClass *klass,
                                             GtsSurface *surface,
                                             GtsSplitClass *split_class,
                                             GtsKeyFunc cost_func,
                                             gpointer cost_data,
                                             GtsCoarsenFunc coarsen_func,
                                             gpointer coarsen_data,
                                             GtsStopFunc stop_func,
                                             gpointer stop_data,
                                             gdouble minangle);

This function works in exactly the same way as the gts_surface_coarsen() function, except that the history of edge collapse is saved in an array of GtsSplit objects. This allows for dynamic continuous multiresolution control of the input surface.

klass : a GtsPSurfaceClass.
surface : a GtsSurface.
split_class : a GtsSplitClass to use for the new progressive surface.
cost_func : cost function for the edge collapse algorithm.
cost_data : data to pass to cost_func.
coarsen_func : the function returning the vertex replacement for the edge collapse.
coarsen_data : data to pass to coarsen_func.
stop_func : the function to call to decide whether to stop the coarsening process.
stop_data : data to pass to stop_func.
minangle : the minimum angle allowable between two neighboring triangles. This is used to avoid introducing folds in the mesh during simplification.
Returns : a new progressive surface.


gts_psurface_add_vertex ()

GtsSplit*   gts_psurface_add_vertex         (GtsPSurface *ps);

Adds a vertex to the progressive surface ps by expanding the next available GtsSplit.

ps : a GtsPSurface.
Returns : the expanded GtsSplit or NULL if all the GtsSplit have already been expanded.


gts_psurface_remove_vertex ()

GtsSplit*   gts_psurface_remove_vertex      (GtsPSurface *ps);

Removes one vertex from the progressive surface ps by collapsing the first available GtsSplit.

ps : a GtsPSurface.
Returns : the collapsed GtsSplit or NULL if all the GtsSplit have already been collapsed.


gts_psurface_set_vertex_number ()

void        gts_psurface_set_vertex_number  (GtsPSurface *ps,
                                             guint n);

Performs the required number of collapses or expansions to set the number of vertices of ps to n.

ps : a GtsPSurface.
n : a number of vertices.


gts_psurface_get_vertex_number ()

guint       gts_psurface_get_vertex_number  (GtsPSurface *ps);

ps : a GtsPSurface.
Returns : the current number of vertices of ps.


gts_psurface_min_vertex_number ()

guint       gts_psurface_min_vertex_number  (GtsPSurface *ps);

ps : a GtsPSurface.
Returns : the minimum number of vertices of ps i.e. the number of vertices if all the GtsSplit were collapsed.


gts_psurface_max_vertex_number ()

guint       gts_psurface_max_vertex_number  (GtsPSurface *ps);

ps : a GtsPSurface.
Returns : the maximum number of vertices of ps i.e. the number of vertices if all the GtsSplit were expanded.


gts_psurface_foreach_vertex ()

void        gts_psurface_foreach_vertex     (GtsPSurface *ps,
                                             GtsFunc func,
                                             gpointer data);

Calls func for each (potential) vertex of ps, whether actually used or not. The vertices are called in the order they were created during the edge collapse operation.

ps : a GtsPSurface.
func : a function to call for each vertex of ps.
data : data to be passed to func.


gts_psurface_open ()

GtsPSurface* gts_psurface_open              (GtsPSurfaceClass *klass,
                                             GtsSurface *s,
                                             GtsSplitClass *split_class,
                                             FILE *fptr,
                                             guint *line);

Creates a new GtsPSurface prepared for input from the file fptr containing a valid GTS representation of a progressive surface. The initial shape of the progressive surface is loaded into s.

Before being usable as such this progressive surface must be closed using gts_psurface_close(). While open however, the functions gts_psurface_get_vertex_number(), gts_psurface_min_vertex_number() and gts_psurface_max_vertex_number() can still be used.

klass : a GtsPSurfaceClass.
s : a GtsSurface.
split_class : a GtsSplitClass to use for the GtsSplit.
fptr : a file pointer.
line : NULL or a pointer to a variable to fill with the line number in case of an error in the file format.
Returns : a new GtsPSurface or NULL if there was a format error while reading the file, in which case line is set to the line where the error occured.


gts_psurface_read_vertex ()

GtsSplit*   gts_psurface_read_vertex        (GtsPSurface *ps,
                                             FILE *fptr);

Reads in one vertex split operation from fptr and performs the expansion.

ps : a GtsPSurface prealably created with gts_psurface_open().
fptr : a file pointer.
Returns : the newly created GtsSplit or NULL if no vertex split could be read from fptr.


gts_psurface_close ()

void        gts_psurface_close              (GtsPSurface *ps);

Closes a progressive surface.

ps : a GtsPSurface prealably created with gts_psurface_open().


gts_psurface_write ()

void        gts_psurface_write              (GtsPSurface *ps,
                                             FILE *fptr);

Writes to fptr a GTS progressive surface description.

ps : a GtsPSurface.
fptr : a file pointer.