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,
                                             GtsFile *f);
GtsSplit*   gts_psurface_read_vertex        (GtsPSurface *ps,
                                             GtsFile *fp);
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;
  GPtrArray * 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.

GtsObject object

The parent object.

GtsSurface *s

The GtsSurface being refined or coarsened by operations on the progressive surface.

GPtrArray *split

GtsSplitClass *split_class

guint pos

guint min

GPtrArray *vertices

GPtrArray *faces


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,
                                             GtsFile *f);

Creates a new GtsPSurface prepared for input from the file f 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.

f :

a GtsFile.

Returns :

a new GtsPSurface or NULL if there was a format error while reading the file, in which case f contains information about the error.


gts_psurface_read_vertex ()

GtsSplit*   gts_psurface_read_vertex        (GtsPSurface *ps,
                                             GtsFile *fp);

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

If an error occurs while reading the file, the error field of fp is set.

ps :

a GtsPSurface prealably created with gts_psurface_open().

fp :

a GtsFile.

Returns :

the newly created GtsSplit or NULL if no vertex split could be read from fp.


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.