/*
Copyright (C) 2011 Andrew Cotter
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
*/
/**
\file dynamic_wsp.h
\brief Dynamic WSP interface
*/
#ifndef __DYNAMIC_WSP_H__
#define __DYNAMIC_WSP_H__
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/*============================================================================
DynamicWSP_Handle and DynamicWSP_PointHandle typedefs
============================================================================*/
/**
\brief Opaque handle type for a well-spaced point set
*/
typedef void* DynamicWSP_Handle;
/**
\brief Opaque handle type for a single point
*/
typedef void const* DynamicWSP_PointHandle;
/*============================================================================
DynamicWSP_Error function
============================================================================*/
/**
\brief Returns an error string
If one of the other DynamicWSP functions returns true, you may call this
function to retreive a string description of the error.
\result Error string
*/
extern char const* DynamicWSP_Error();
/*============================================================================
DynamicWSP_Allocate function
============================================================================*/
/**
\brief Allocates a new well-spaced point set
\param pHandle (Output) handle of created well-spaced point set
\param dimension (Input) Dimension of the space
\param rho (Input) Well-spacedness parameter (rho > 1 )
\param beta (Input) Clipped Voronoi parameter (rho < beta < 2*rho)
\result False on success, true on error
*/
extern bool DynamicWSP_Allocate(
DynamicWSP_Handle* const pHandle,
unsigned int const dimension,
double const rho,
double const beta
);
/*============================================================================
DynamicWSP_Free function
============================================================================*/
/**
\brief Frees a well-spaced point set
\param handle (Input) handle of well-spaced point set
\result False on success, true on error
*/
extern bool DynamicWSP_Free( DynamicWSP_Handle const handle );
/*============================================================================
DynamicWSP_Insert function
============================================================================*/
/**
\brief Inserts a new point into the well-spaced point set
The insertion of this point is likely to break well-spacedness--call
DynamicWSP_Refine() to bring the set of Steiner points up-to-date with your
changes.
The pPointHandle parameter will normally be set to a handle of the
newly-inserted point. However, if (and only if) a point with exactly the
same coordinates already exists, insertion will not take place, and it will
be set to NULL. In this case, an error will not be returned.
Some number of Steiner points may be destroyed by a call to this function,
so you should not use any Steiner point handles which you might have saved.
After calling DynamicWSP_Refine(), you may retreive a list of those Steiner
points which were inserted and erased since the previous call to
DynamicWSP_Refine() using DynamicWSP_GetRecentSteinerPointHandles(). You
may likewise, at any time, retreive an up-to-date list of all Steiner
points by calling DynamicWSP_GetSteinerPointHandles().
\param handle (Input) handle of well-spaced point set
\param pPointHandle (Output) handle of inserted point
\param coordinates (Input) d-dimensional array of coordinates (each between 0 and 1, exclusive)
\result False on success, true on error
*/
extern bool DynamicWSP_Insert(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle* const pPointHandle,
double const* const coordinates
);
/*============================================================================
DynamicWSP_Erase function
============================================================================*/
/**
\brief Erases an inserted point from the well-spaced point set
This function is only for erasing points which were inserted with
DynamicWSP_Insert(). Steiner points cannot be erased using this function.
The erasure of this point is likely to break well-spacedness--call
DynamicWSP_Refine() to bring the set of Steiner points up-to-date with your
changes.
The erased point will be destroyed, and will no longer be valid--you should
not pass it as a parameter to any function which takes a point handle as a
parameter. Additionally, some number of Steiner points may be destroyed by
a call to this function, so you should likewise not use any Steiner point
handles which you might have saved. After calling DynamicWSP_Refine(), you
may retreive a list of those Steiner points which were inserted and erased
since the previous call to DynamicWSP_Refine() using
DynamicWSP_GetRecentSteinerPointHandles(). You may likewise, at any time,
retreive an up-to-date list of all Steiner points by calling
DynamicWSP_GetSteinerPointHandles().
\param handle (Input) handle of well-spaced point set
\param pointHandle (Input) handle of point to erase
\result False on success, true on error
*/
extern bool DynamicWSP_Erase(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle const pointHandle
);
/*============================================================================
DynamicWSP_GetCoordinates function
============================================================================*/
/**
\brief Gets the coordinates of a point
This function can be called on handles of either points inserted using
DynamicWSP_Insert(), or Steiner points.
\param handle (Input) handle of well-spaced point set
\param pointHandle (Input) handle of point
\param coordinates (Output) d-dimensional array of coordinates
\result False on success, true on error
*/
extern bool DynamicWSP_GetCoordinates(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle const pointHandle,
double* const coordinates
);
/*============================================================================
DynamicWSP_IsSteiner function
============================================================================*/
/**
\brief Checks if a point is a Steiner point
This function can be called on handles of either points inserted using
DynamicWSP_Insert(), or Steiner points. The pIsSteiner parameter will be
set to true if the point is of the latter type, false if the former.
\param handle (Input) handle of well-spaced point set
\param pointHandle (Input) handle of point
\param pIsSteiner (Output) true if this is a Steiner point, false otherwise
\result False on success, true on error
*/
extern bool DynamicWSP_IsSteiner(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle const pointHandle,
bool* const pIsSteiner
);
/*============================================================================
DynamicWSP_Refine function
============================================================================*/
/**
\brief Inserts/erases Steiner points in order to make the input set well-spaced
Call this function after performing some number of calls to
DynamicWSP_Insert() and/or DynamicWSP_Erase(), to make the point set
well-spaced.
After calling this function, the sets of Steiner points which were either
inserted or erased may be retreived by calling
DynamicWSP_GetRecentSteinerPointHandles();
\param handle (Input) handle of well-spaced point set
\param threads (Input) Number of threads to use (no larger than DYNAMIC_WSP_MAXIMUM_THREADS (defined in the Makefile))
\result False on success, true on error
*/
extern bool DynamicWSP_Refine(
DynamicWSP_Handle const handle,
unsigned int const threads
);
/*============================================================================
DynamicWSP_GetPointHandles function
============================================================================*/
/**
\brief Gets an array of all inserted point handles
This function only returns handles for those points inserted using
DynamicWSP_Insert() (and not yet erased using DynamicWSP_Erase()). Steiner
point handles are retrieved using DynamicWSP_GetSteinerPointHandles().
The input/output parameter pLength is used both to pass the length of the
destination array (zero is allowed, in which case the destination array may
be NULL), and to retrieve the number of points available. If the
destination array is either too large or too small, then *pLength will be
set to the number of points returned, or the required size of the array,
respectively.
If the destination array is too small, an error will not be
returned, and the array will be filled with as many handles as it can
contain. This condition can be detected by inspecting *pComplete.
\param handle (Input) handle of well-spaced point set
\param pointHandles (Output) Array of point handles
\param pLength (Input/Output) Length of handle array / number of points
\param pComplete (Output) True if the handle array was large enough, false otherwise
\result False on success, true on error
*/
extern bool DynamicWSP_GetPointHandles(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle* const pointHandles,
unsigned int* pLength,
bool* pComplete
);
/*============================================================================
DynamicWSP_GetSteinerPointHandles function
============================================================================*/
/**
\brief Gets an array of all Steiner point handles
This function only returns handles for Steiner points. Explicitly-inserted
point handles are retrieved using DynamicWSP_GetPointHandles().
The input/output parameter pLength is used both to pass the length of the
destination array (zero is allowed, in which case the destination array may
be NULL), and to retrieve the number of points available. If the
destination array is either too large or too small, then *pLength will be
set to the number of points returned, or the required size of the array,
respectively.
If the destination array is too small, an error will not be
returned, and the array will be filled with as many handles as it can
contain. This condition can be detected by inspecting *pComplete.
\param handle (Input) handle of well-spaced point set
\param pointHandles (Output) Array of point handles
\param pLength (Input/Output) Length of handle array / number of points
\param pComplete (Output) True if the handle array was large enough, false otherwise
\result False on success, true on error
*/
extern bool DynamicWSP_GetSteinerPointHandles(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle* const pointHandles,
unsigned int* pLength,
bool* pComplete
);
/*============================================================================
DynamicWSP_GetRecentSteinerPointHandles function
============================================================================*/
/**
\brief Gets an array of all recently-updated Steiner point handles
This function returns lists of all Steiner point handles which were either
inserted or erased during the most recent call to DynamicWSP_Refine() and
all DynamicWSP_Insert() and DynamicWSP_Erase() calls leading up to it. If
you call this function immediately after calling DynamicWSP_Refine()
(before any new calls to DynamicWSP_Insert() or DynamicWSP_Erase()), then
it will return all Steiner points which were inserted or erased since the
previous call to DynamicWSP_Refine().
The input/output parameters pInsertedLength and pErasedLength are used both
to pass the lengths of the destination arrays (zero is allowed, in which
case the corresponding destination array may be NULL), and to retrieve the
number of points available. If a destination array is either too large or
too small, then the corresponding length will be set to the number of
points returned, or the required size of the array, respectively.
If a destination array is too small, an error will not be
returned, and the array will be filled with as many handles as it can
contain. This condition can be detected by inspecting *pInsertedComplete
and *pErasedComplete.
The erased Steiner points will be destroyed, and will no longer be
valid--you should not pass them as parameters to any function which takes a
point handle as a parameter.
\param handle (Input) handle of well-spaced point set
\param insertedPointHandles (Output) Array of inserted Steiner point handles
\param pInsertedLength (Input/Output) Length of inserted handle array / number of points
\param pInsertedComplete (Output) True if the inserted handle array was large enough, false otherwise
\param erasedPointHandles (Output) Array of erased Steiner point handles
\param pErasedLength (Input/Output) Length of erased handle array / number of points
\param pErasedComplete (Output) True if the erased handle array was large enough, false otherwise
\result False on success, true on error
*/
extern bool DynamicWSP_GetRecentSteinerPointHandles(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle* const insertedPointHandles,
unsigned int* pInsertedLength,
bool* pInsertedComplete,
DynamicWSP_PointHandle* const erasedPointHandles,
unsigned int* pErasedLength,
bool* pErasedComplete
);
/*============================================================================
DynamicWSP_GetNearestNeighborHandle function
============================================================================*/
/**
\brief Gets the nearest neighbor of a point
This function can be called on handles of either points inserted using
DynamicWSP_Insert(), or Steiner points. The result, likewise, could be
either type of point.
\param handle (Input) handle of well-spaced point set
\param pointHandle (Input) handle of point
\param pPointHandle (Output) handle of nearest neighbor
\result False on success, true on error
*/
extern bool DynamicWSP_GetNearestNeighborHandle(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle const pointHandle,
DynamicWSP_PointHandle* const pPointHandle
);
/*============================================================================
DynamicWSP_GetVoronoiNeighborHandless function
============================================================================*/
/**
\brief Gets an array of all Voronoi neighbors of a point
This function can be called on handles of either points inserted using
DynamicWSP_Insert(), or Steiner points. The resulting array, likewise, can
contain both types of point. Furthermore, this function may only be called
on a well-spaced point set (so only immediately after a call to
DynamicWSP_Refine()).
The input/output parameter pLength is used both to pass the length of the
destination array (zero is allowed, in which case the destination array may
be NULL), and to retrieve the number of points available. If the
destination array is either too large or too small, then *pLength will be
set to the number of points returned, or the required size of the array,
respectively.
If the destination array is too small, an error will not be
returned, and the array will be filled with as many handles as it can
contain. This condition can be detected by inspecting *pComplete.
\param handle (Input) handle of well-spaced point set
\param pointHandle (Input) handle of point
\param pointHandles (Output) Array of Voronoi neighbor handles
\param pLength (Input/Output) Length of handle array / number of points
\param pComplete (Output) True if the handle array was large enough, false otherwise
\result False on success, true on error
*/
extern bool DynamicWSP_GetVoronoiNeighborHandles(
DynamicWSP_Handle const handle,
DynamicWSP_PointHandle const pointHandle,
DynamicWSP_PointHandle* const pointHandles,
unsigned int* pLength,
bool* pComplete
);
#ifdef __cplusplus
} /* extern "C" */
#endif /* __cplusplus */
#endif /* __DYNAMIC_WSP_H__ */