IPointShape
Functions
Detailed Description
-
class IPointShape : public RED::IREDObject
This interface gives access to the point’s properties.
@related Point Shapes , Building Basic Primitives, class RED::IShape
Points geometries are just raw lists of vertices.
Points are similar to meshes (see RED::IMeshShape) in the sense that they also feature 16 data channels that can store each point’s vertex attributes.
Public Functions
-
virtual RED_RC GetVerticesCount(int &oCount, int iStateNumber = -1) const = 0
Gets the number of vertices in the point shape.
Returns the number of vertices in the point shape. Each used data channel is sized to contain information for the same number of vertices.
See also \ref bk_pointcloud.
- Parameters
oCount – The number of vertices in the point shape.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetVertexArray(const void *&oArray, int &oSize, RED::MESH_FORMAT &oFormat, int iStateNumber = -1) const = 0
Read-only access to the vertex array of the point shape.
Returns the vertex array of the point shape, and its size and type of data per vertex. If this point shape is to be used with the ray-tracer, it expects three MFT_FLOAT coordinates.
See also \ref bk_pointcloud.
- Parameters
oArray – Address of the vertex array of the point shape. Returns NULL if the point shape has no bound vertex array yet. The returned data is for read access only.
oSize – Number of coordinates per vertex (1,2,3, or 4).
oFormat – Format of the returned data.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetVertexArray(void *&oArray, int &oSize, RED::MESH_FORMAT &oFormat, const RED::State &iState) = 0
Read-write access to the vertex array of the point shape.
Returns the current vertex array of the point shape, its size and type of data per vertex. If this point shape is to be used with the ray-tracer, it expects three MFT_FLOAT coordinates. The data array can be modified, but the format and size of the array can’t be changed.
See also \ref bk_pointcloud.
- Parameters
oArray – Address of the vertex array of the point shape. Returns NULL if the point shape has no bound vertex array yet. The returned data is for read / write access.
oSize – Number of coordinates per vertex (1,2,3, or 4).
oFormat – Format of the returned data.
iState – Current transaction.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetArray(const void *&oArray, int &oSize, RED::MESH_FORMAT &oFormat, RED::MESH_CHANNEL iChannelId, int iStateNumber = -1) const = 0
Read-only access an array through its channel identifier.
Returns the array whose channel identifier is ‘iChannelId’.
See also \ref bk_pointcloud.
- Parameters
oArray – The address of the array in the point shape. Returns NULL if the point shape has no data in that array. The returned data is for read access only.
oSize – Number of coordinates per vertex (1,2,3, or 4).
oFormat – Format of the returned data.
iChannelId – Requested channel id.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetArray(void *&oArray, int &oSize, RED::MESH_FORMAT &oFormat, RED::MESH_CHANNEL iChannelId, const RED::State &iState) = 0
Read-write access an array through its channel identifier.
Returns the array whose channel identifier is ‘iChannelId’.
See also \ref bk_pointcloud.
- Parameters
oArray – The address of the array in the point shape. Returns NULL if the point shape has no data in that array. The returned data is for read / write access.
oSize – Number of coordinates per vertex (1,2,3, or 4).
oFormat – Format of the returned data.
iChannelId – Requested channel id.
iState – Current transaction.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetArray(const void *&oData, RED::MESH_CHANNEL iChannelId, int iStateNumber = -1) const = 0
Read-only access an array data through its channel identifier.
Returns the data in the array whose channel id is ‘iChannelId’.
See also \ref bk_pointcloud.
- Parameters
oData – Address of the array in the point shape. Returns NULL if the point shape has no data in that array. The returned data is for read access only.
iChannelId – Requested channel id.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetArray(void *&oData, RED::MESH_CHANNEL iChannelId, const RED::State &iState) = 0
Read-write access an array data through its channel identifier.
Returns the data in the array whose channel id is ‘iChannelId’.
See also \ref bk_pointcloud.
- Parameters
oData – Address of the array in the point shape. Returns NULL if the point shape has no data in that array. The returned data is for read / write access.
iChannelId – Requested channel id.
iState – Current transaction.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
Is the specified channel being shared?
- Parameters
oShared – true if the data in ‘iChannelId’ is shared. false otherwise (not shared or no data).
iChannelId – Identifier of the channel to check.
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC SetArray(RED::MESH_CHANNEL iChannelId, const void *iData, int iVerticesCount, int iSize, RED::MESH_FORMAT iFormat, const RED::State &iState) = 0
Defines the contents of a data channel.
This method defines the contents of the targeted channel. We have two possible memory behaviors here:
Copy the provided input data in the class. We try to be memory conservative in this case and to reuse existing memory that could have been allocated earlier on for the same data channel.
Provide no ‘iData’ at all. In this case, we allocate an array using the dimension parameters provided. This array is not initialized by the call, and can be accessed to be filled.
Note that we define the number of vertices as a parameter of the method, to be able to figure out the total size of our data channel. All channels must be configured with the same number of vertices. The method fails if the provided number of vertices don’t match the current size of other channels.
See also \ref bk_pointcloud.
- Parameters
iChannelId – Targeted channel that’ll receive the contents of ‘iData’.
iData – Data array. NULL to let the method allocate an array itself.
iVerticesCount – Number of vertices for all channels.
iSize – Number of coordinates per vertex in [1-4].
iFormat – Format of each coordinate.
iState – Current transaction.
- Returns
RED_OK when the data channel could have been defined,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL if the number of vertices does not match the current size of other channels.
Defines the contents of a data channel.
This method is similar to RED::IPointShape::SetArray, except that the memory control of the provided array is let to the caller’s responsibility. Shared arrays differ in their behaviors from regular arrays in several ways:
The address of a shared array do not change with new transactions. A regular array is copied to a new version when modified so that it can be modified without stalling a multi-threaded rendering that may occur on the last closed transaction version of the data. A shared array is not duplicated and therefore the returned address can’t be overwritten if multi-threaded rendering is used.
RED::IPointShape::DeleteArray and RED::IPointShape::DeleteAllArrays don’t release the shared memory but behave normally for all other aspects of the method.
Sharing with a RED::IMeshShape array must be done carefully. If the mesh is edited after the sharing has occurred, then the mesh’s arrays base addresses will change due to the multi-threading security of REDsdk’s transaction model. Then the sharing may become invalid, and should be done again to ensure that we share the appropriate address.
- Parameters
iChannelId – Targeted channel.
iData – Shared data array.
iVerticesCount – Number of vertices for all channels.
iSize – Number of coordinates per vertex in [1-4].
iFormat – Format of each coordinate.
iState – Current transaction.
- Returns
RED_OK when the data channel could have been shared,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL if the number of vertices does not match the current size of other channels.
-
virtual RED_RC DeleteArray(RED::MESH_CHANNEL iChannelId, const RED::State &iState) = 0
Deletes the contents of a data channel.
This method deletes the contents of a data channel identified by its number in the object. The corresponding array - if found - is freed from memory.
- Parameters
iChannelId – Id of the channel to release.
iState – Current transaction.
- Returns
RED_OK when the channel’s data could be released,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC DeleteAllArrays(const RED::State &iState) = 0
Deletes the contents of all data channels.
Works as RED::IPointShape::DeleteArray, for all channels in the object.
- Parameters
iState – Current transaction.
- Returns
RED_OK when the channel’s data could be released,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC GetPoints(const int *&oIndex, int &oIndexCount, int iStateNumber = -1) const = 0
Read-only access to the list of indices in the point shape.
Returns the list of points in the line. Each index value indicates the number of the vertex to access in the shape’s arrays.
See also \ref bk_pointcloud.
- Parameters
oIndex – Points index list.
oIndexCount – Number of indices.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetPoints(int *&oIndex, int &oIndexCount, const RED::State &iState) = 0
Read-write access to the list of triangles in the point shape.
Returns the list of indices in the shape. Each index value indicates the number of the vertex to access in the shape’s arrays.
See also \ref bk_pointcloud.
- Parameters
oIndex – Points index list.
oIndexCount – Number of indices.
iState – Current transaction.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC GetPointsCount(int &oCount, int iStateNumber = -1) const = 0
Returns the number of indices in the shape.
See also \ref bk_pointcloud.
- Parameters
oCount – The number of indices in the shape.
iStateNumber – Queried state number.
- Returns
RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
Is the mesh’s point array being shared?
- Parameters
oShared – true if the object point index list is shared. false otherwise (not shared or no data).
iStateNumber – Queried state number.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
-
virtual RED_RC AddPoints(const int *iPointIndex, int iIndexCount, const RED::State &iState) = 0
Adds points to the object’s list.
This method adds points to the list of points to draw in the object. The input information is being copied and appended at the end of the existing information already set.
It’s possible to provide no point index array at all. In this case, the size of the point list is increased by ‘iNbIndex’, and all indices in the added list are set to zero. Then the quick point edition method RED::IPointShape::SetIndex can be used to change the list on the fly, without memory allocations penalties that would occur with a 1 by 1 addition of all points.
See also \ref bk_pointcloud.
- Parameters
iPointIndex – Index array for the added point. Contains one (int) value per point. Each index indicates the number of the vertex to reference in the object’s data channels. When NULL, the method creates an index array set to zero by default, sized to the number of requested points.
iIndexCount – Number of points to add (must be >=0)
iState – Current transaction.
- Returns
RED_OK when the points could be added,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC SetPoint(int iNumIndex, int iP0, const RED::State &iState) = 0
Modifies the index of a given point.
This method can be used to quickly change the index defining a point. The target point is ‘iNumPoint’, and the new index to use for it is [iP0].
- Parameters
iNumIndex – Point to modify.
iP0 – Point vertex number.
iState – Current transaction.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_FAIL otherwise.
Uses a shared point list for the object.
If the object was owning a list of points, this list is deleted and replaced by the shared list provided to the method.
- Parameters
iPointIndex – Index array for the added triangles. Must point on a valid array of one (int) for each point vertex index.
iPointCount – Number of points in ‘iPointIndex’.
iState – Current transaction.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC DeletePoints(const RED::State &iState) = 0
Deletes all indices in the point shape’s list.
This method removes all indices from the list within the point shape. The memory formerly used is released.
- Parameters
iState – Current transaction.
- Returns
RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal memory allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC Collapse(double iTolerance, const RED::State &iState) = 0
Removes duplicate vertices.
This method removes all duplicates vertices in the mesh and changes all triangles indices accordingly. Two vertices are considered identical if:
Their position are identical at ‘iTolerance’,
All their other geometrical attributes are identical at ‘iTolerance’.
Note that the method can’t operate on point shapes with shared arrays as it needs to reallocate the vertex memory to eliminate redundancies.
- Parameters
iTolerance – Numerical tolerance used for matching tests.
iState – Current transaction.
- Returns
RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL if an unexpected error has occurred,
RED_FAIL if the shape has shared arrays.
-
virtual RED_RC CopyFrom(const RED::Object &iPoint, const RED::State &iState, int iSrcStateNumber = -1) = 0
Copies the content of a point shape instance to the current object.
This method will work for only two instances of the same concrete class.
- Parameters
iPoint – Reference to the object to copy from.
iState – Current transaction.
iSrcStateNumber – State from which the source point shape must be copied.
- Returns
RED_OK on success,
RED_BAD_PARAM if ‘iPoint’ and ‘this’ are from different classes, or if ‘iSrcStateNumber’ is invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL for any other error.
-
virtual RED_RC GetVerticesCount(int &oCount, int iStateNumber = -1) const = 0
