style cleanup: header comments, use more doxy compat formatting

This commit is contained in:
Campbell Barton 2012-06-27 17:48:39 +00:00
parent ae2f3a4e5e
commit d008807a2d
2 changed files with 81 additions and 82 deletions

@ -97,10 +97,10 @@ extern "C" {
void *MEM_dupallocN(void *vmemh) WARN_UNUSED;
/**
* Reallocates a block of memory, and returns pointer to the newly
* allocated block, the old one is freed. this is not as optimized
* as a system realloc but just makes a new allocation and copies
* over from existing memory. */
* Reallocates a block of memory, and returns pointer to the newly
* allocated block, the old one is freed. this is not as optimized
* as a system realloc but just makes a new allocation and copies
* over from existing memory. */
void *MEM_reallocN(void *vmemh, size_t len) WARN_UNUSED;
/**
@ -110,13 +110,13 @@ extern "C" {
void *MEM_callocN(size_t len, const char * str) WARN_UNUSED;
/** Allocate a block of memory of size len, with tag name str. The
* name must be a static, because only a pointer to it is stored !
* */
* name must be a static, because only a pointer to it is stored !
* */
void *MEM_mallocN(size_t len, const char * str) WARN_UNUSED;
/** Same as callocN, clears memory and uses mmap (disk cached) if supported.
Can be free'd with MEM_freeN as usual.
* */
* Can be free'd with MEM_freeN as usual.
* */
void *MEM_mapallocN(size_t len, const char * str) WARN_UNUSED;
/** Print a list of the names and sizes of all allocated memory
@ -143,7 +143,7 @@ extern "C" {
int MEM_check_memory_integrity(void);
/** Set thread locking functions for safe memory allocation from multiple
threads, pass NULL pointers to disable thread locking again. */
* threads, pass NULL pointers to disable thread locking again. */
void MEM_set_lock_callback(void (*lock)(void), void (*unlock)(void));
/** Attempt to enforce OSX (or other OS's) to have malloc and stack nonzero */
@ -195,4 +195,3 @@ public: \
#endif
#endif

@ -28,12 +28,14 @@
#ifndef __BKE_DERIVEDMESH_H__
#define __BKE_DERIVEDMESH_H__
/*
/**
* Basic design of the DerivedMesh system:
*
* DerivedMesh is a common set of interfaces for mesh systems.
*
* There are three main mesh data structures in Blender: Mesh, CDDM, and BMesh.
* There are three main mesh data structures in Blender:
* #Mesh, #CDDerivedMesh and #BMesh.
*
* These, and a few others, all implement DerivedMesh interfaces,
* which contains unified drawing interfaces, a few utility interfaces,
* and a bunch of read-only interfaces intended mostly for conversion from
@ -67,7 +69,6 @@
* as it is and stick with using BMesh and CDDM.
*/
#include "DNA_customdata_types.h"
#include "DNA_meshdata_types.h"
@ -151,7 +152,7 @@ typedef enum DMDirtyFlag {
typedef struct DerivedMesh DerivedMesh;
struct DerivedMesh {
/* Private DerivedMesh data, only for internal DerivedMesh use */
/** Private DerivedMesh data, only for internal DerivedMesh use */
CustomData vertData, edgeData, faceData, loopData, polyData;
int numVertData, numEdgeData, numTessFaceData, numLoopData, numPolyData;
int needsFree; /* checked on ->release, is set to 0 for cached results */
@ -162,10 +163,10 @@ struct DerivedMesh {
float auto_bump_scale;
DMDirtyFlag dirty;
/* calculate vert and face normals */
/** Calculate vert and face normals */
void (*calcNormals)(DerivedMesh *dm);
/* recalculates mesh tessellation */
/** Recalculates mesh tessellation */
void (*recalcTessellation)(DerivedMesh *dm);
/* Misc. Queries */
@ -177,7 +178,7 @@ struct DerivedMesh {
int (*getNumLoops)(DerivedMesh *dm);
int (*getNumPolys)(DerivedMesh *dm);
/* copy a single vert/edge/tessellated face from the derived mesh into
/** Copy a single vert/edge/tessellated face from the derived mesh into
* *{vert/edge/face}_r. note that the current implementation
* of this function can be quite slow, iterating over all
* elements (editmesh)
@ -186,7 +187,7 @@ struct DerivedMesh {
void (*getEdge)(DerivedMesh *dm, int index, struct MEdge *edge_r);
void (*getTessFace)(DerivedMesh *dm, int index, struct MFace *face_r);
/* return a pointer to the entire array of verts/edges/face from the
/** Return a pointer to the entire array of verts/edges/face from the
* derived mesh. if such an array does not exist yet, it will be created,
* and freed on the next ->release(). consider using getVert/Edge/Face if
* you are only interested in a few verts/edges/faces.
@ -197,7 +198,7 @@ struct DerivedMesh {
struct MLoop *(*getLoopArray)(DerivedMesh * dm);
struct MPoly *(*getPolyArray)(DerivedMesh * dm);
/* copy all verts/edges/faces from the derived mesh into
/** Copy all verts/edges/faces from the derived mesh into
* *{vert/edge/face}_r (must point to a buffer large enough)
*/
void (*copyVertArray)(DerivedMesh *dm, struct MVert *vert_r);
@ -206,7 +207,7 @@ struct DerivedMesh {
void (*copyLoopArray)(DerivedMesh *dm, struct MLoop *loop_r);
void (*copyPolyArray)(DerivedMesh *dm, struct MPoly *poly_r);
/* return a copy of all verts/edges/faces from the derived mesh
/** Return a copy of all verts/edges/faces from the derived mesh
* it is the caller's responsibility to free the returned pointer
*/
struct MVert *(*dupVertArray)(DerivedMesh * dm);
@ -215,7 +216,7 @@ struct DerivedMesh {
struct MLoop *(*dupLoopArray)(DerivedMesh * dm);
struct MPoly *(*dupPolyArray)(DerivedMesh * dm);
/* return a pointer to a single element of vert/edge/face custom data
/** Return a pointer to a single element of vert/edge/face custom data
* from the derived mesh (this gives a pointer to the actual data, not
* a copy)
*/
@ -223,7 +224,7 @@ struct DerivedMesh {
void *(*getEdgeData)(DerivedMesh * dm, int index, int type);
void *(*getTessFaceData)(DerivedMesh * dm, int index, int type);
/* return a pointer to the entire array of vert/edge/face custom data
/** Return a pointer to the entire array of vert/edge/face custom data
* from the derived mesh (this gives a pointer to the actual data, not
* a copy)
*/
@ -231,7 +232,7 @@ struct DerivedMesh {
void *(*getEdgeDataArray)(DerivedMesh * dm, int type);
void *(*getTessFaceDataArray)(DerivedMesh * dm, int type);
/* retrieves the base CustomData structures for
/** Retrieves the base CustomData structures for
* verts/edges/tessfaces/loops/facdes*/
CustomData *(*getVertDataLayout)(DerivedMesh * dm);
CustomData *(*getEdgeDataLayout)(DerivedMesh * dm);
@ -239,12 +240,12 @@ struct DerivedMesh {
CustomData *(*getLoopDataLayout)(DerivedMesh * dm);
CustomData *(*getPolyDataLayout)(DerivedMesh * dm);
/*copies all customdata for an element source into dst at index dest*/
/** Copies all customdata for an element source into dst at index dest */
void (*copyFromVertCData)(DerivedMesh *dm, int source, CustomData *dst, int dest);
void (*copyFromEdgeCData)(DerivedMesh *dm, int source, CustomData *dst, int dest);
void (*copyFromFaceCData)(DerivedMesh *dm, int source, CustomData *dst, int dest);
/* optional grid access for subsurf */
/** Optional grid access for subsurf */
int (*getNumGrids)(DerivedMesh *dm);
int (*getGridSize)(DerivedMesh *dm);
struct CCGElem **(*getGridData)(DerivedMesh * dm);
@ -255,7 +256,7 @@ struct DerivedMesh {
unsigned int **(*getGridHidden)(DerivedMesh * dm);
/* Iterate over each mapped vertex in the derived mesh, calling the
/** Iterate over each mapped vertex in the derived mesh, calling the
* given function with the original vert and the mapped vert's new
* coordinate and normal. For historical reasons the normal can be
* passed as a float or short array, only one should be non-NULL.
@ -265,7 +266,7 @@ struct DerivedMesh {
const float no_f[3], const short no_s[3]),
void *userData);
/* Iterate over each mapped edge in the derived mesh, calling the
/** Iterate over each mapped edge in the derived mesh, calling the
* given function with the original edge and the mapped edge's new
* coordinates.
*/
@ -274,7 +275,7 @@ struct DerivedMesh {
const float v0co[3], const float v1co[3]),
void *userData);
/* Iterate over each mapped face in the derived mesh, calling the
/** Iterate over each mapped face in the derived mesh, calling the
* given function with the original face and the mapped face's (or
* faces') center and normal.
*/
@ -283,51 +284,51 @@ struct DerivedMesh {
const float cent[3], const float no[3]),
void *userData);
/* Iterate over all vertex points, calling DO_MINMAX with given args.
/** Iterate over all vertex points, calling DO_MINMAX with given args.
*
* Also called in Editmode
*/
void (*getMinMax)(DerivedMesh *dm, float min_r[3], float max_r[3]);
/* Direct Access Operations */
/* o Can be undefined */
/* o Must be defined for modifiers that only deform however */
/** Direct Access Operations
* - Can be undefined
* - Must be defined for modifiers that only deform however */
/* Get vertex location, undefined if index is not valid */
/** Get vertex location, undefined if index is not valid */
void (*getVertCo)(DerivedMesh *dm, int index, float co_r[3]);
/* Fill the array (of length .getNumVerts()) with all vertex locations */
/** Fill the array (of length .getNumVerts()) with all vertex locations */
void (*getVertCos)(DerivedMesh *dm, float (*cos_r)[3]);
/* Get smooth vertex normal, undefined if index is not valid */
/** Get smooth vertex normal, undefined if index is not valid */
void (*getVertNo)(DerivedMesh *dm, int index, float no_r[3]);
/* Get a map of vertices to faces
/** Get a map of vertices to faces
*/
const struct MeshElemMap *(*getPolyMap)(struct Object *ob, DerivedMesh *dm);
/* Get the BVH used for paint modes
/** Get the BVH used for paint modes
*/
struct PBVH *(*getPBVH)(struct Object *ob, DerivedMesh *dm);
/* Drawing Operations */
/* Draw all vertices as bgl points (no options) */
/** Draw all vertices as bgl points (no options) */
void (*drawVerts)(DerivedMesh *dm);
/* Draw edges in the UV mesh (if exists) */
/** Draw edges in the UV mesh (if exists) */
void (*drawUVEdges)(DerivedMesh *dm);
/* Draw all edges as lines (no options)
/** Draw all edges as lines (no options)
*
* Also called for *final* editmode DerivedMeshes
*/
void (*drawEdges)(DerivedMesh *dm, int drawLooseEdges, int drawAllEdges);
/* Draw all loose edges (edges w/ no adjoining faces) */
/** Draw all loose edges (edges w/ no adjoining faces) */
void (*drawLooseEdges)(DerivedMesh *dm);
/* Draw all faces
/** Draw all faces
* o Set face normal or vertex normal based on inherited face flag
* o Use inherited face material index to call setMaterial
* o Only if setMaterial returns true
@ -337,24 +338,24 @@ struct DerivedMesh {
void (*drawFacesSolid)(DerivedMesh *dm, float (*partial_redraw_planes)[4],
int fast, DMSetMaterial setMaterial);
/* Draw all faces using MTFace
* o Drawing options too complicated to enumerate, look at code.
/** Draw all faces using MTFace
* - Drawing options too complicated to enumerate, look at code.
*/
void (*drawFacesTex)(DerivedMesh *dm,
DMSetDrawOptionsTex setDrawOptions,
DMCompareDrawOptions compareDrawOptions,
void *userData);
/* Draw all faces with GLSL materials
/** Draw all faces with GLSL materials
* o setMaterial is called for every different material nr
* o Only if setMaterial returns true
*/
void (*drawFacesGLSL)(DerivedMesh *dm, DMSetMaterial setMaterial);
/* Draw mapped faces (no color, or texture)
* o Only if !setDrawOptions or
* setDrawOptions(userData, mapped-face-index, drawSmooth_r)
* returns true
/** Draw mapped faces (no color, or texture)
* - Only if !setDrawOptions or
* setDrawOptions(userData, mapped-face-index, drawSmooth_r)
* returns true
*
* If drawSmooth is set to true then vertex normals should be set and
* glShadeModel called with GL_SMOOTH. Otherwise the face normal should
@ -371,36 +372,36 @@ struct DerivedMesh {
void *userData,
DMDrawFlag flag);
/* Draw mapped faces using MTFace
* o Drawing options too complicated to enumerate, look at code.
/** Draw mapped faces using MTFace
* - Drawing options too complicated to enumerate, look at code.
*/
void (*drawMappedFacesTex)(DerivedMesh *dm,
DMSetDrawOptions setDrawOptions,
DMCompareDrawOptions compareDrawOptions,
void *userData);
/* Draw mapped faces with GLSL materials
* o setMaterial is called for every different material nr
* o setDrawOptions is called for every face
* o Only if setMaterial and setDrawOptions return true
/** Draw mapped faces with GLSL materials
* - setMaterial is called for every different material nr
* - setDrawOptions is called for every face
* - Only if setMaterial and setDrawOptions return true
*/
void (*drawMappedFacesGLSL)(DerivedMesh *dm,
DMSetMaterial setMaterial,
DMSetDrawOptions setDrawOptions,
void *userData);
/* Draw mapped edges as lines
* o Only if !setDrawOptions or setDrawOptions(userData, mapped-edge)
* returns true
/** Draw mapped edges as lines
* - Only if !setDrawOptions or setDrawOptions(userData, mapped-edge)
* returns true
*/
void (*drawMappedEdges)(DerivedMesh *dm,
DMSetDrawOptions setDrawOptions,
void *userData);
/* Draw mapped edges as lines with interpolation values
* o Only if !setDrawOptions or
* setDrawOptions(userData, mapped-edge, mapped-v0, mapped-v1, t)
* returns true
/** Draw mapped edges as lines with interpolation values
* - Only if !setDrawOptions or
* setDrawOptions(userData, mapped-edge, mapped-v0, mapped-v1, t)
* returns true
*
* NOTE: This routine is optional!
*/
@ -409,32 +410,32 @@ struct DerivedMesh {
DMSetDrawInterpOptions setDrawInterpOptions,
void *userData);
/* Draw all faces with materials
* o setMaterial is called for every different material nr
* o setFace is called to verify if a face must be hidden
/** Draw all faces with materials
* - setMaterial is called for every different material nr
* - setFace is called to verify if a face must be hidden
*/
void (*drawMappedFacesMat)(DerivedMesh *dm,
void (*setMaterial)(void *userData, int, void *attribs),
int (*setFace)(void *userData, int index), void *userData);
/* Release reference to the DerivedMesh. This function decides internally
/** Release reference to the DerivedMesh. This function decides internally
* if the DerivedMesh will be freed, or cached for later use. */
void (*release)(DerivedMesh *dm);
};
/* utility function to initialize a DerivedMesh's function pointers to
/** utility function to initialize a DerivedMesh's function pointers to
* the default implementation (for those functions which have a default)
*/
void DM_init_funcs(DerivedMesh *dm);
/* utility function to initialize a DerivedMesh for the desired number
/** utility function to initialize a DerivedMesh for the desired number
* of vertices, edges and faces (doesn't allocate memory for them, just
* sets up the custom data layers)
*/
void DM_init(DerivedMesh *dm, DerivedMeshType type, int numVerts, int numEdges,
int numFaces, int numLoops, int numPolys);
/* utility function to initialize a DerivedMesh for the desired number
/** utility function to initialize a DerivedMesh for the desired number
* of vertices, edges and faces, with a layer setup copied from source
*/
void DM_from_template(DerivedMesh *dm, DerivedMesh *source,
@ -442,12 +443,12 @@ void DM_from_template(DerivedMesh *dm, DerivedMesh *source,
int numVerts, int numEdges, int numFaces,
int numLoops, int numPolys);
/* utility function to release a DerivedMesh's layers
/** utility function to release a DerivedMesh's layers
* returns 1 if DerivedMesh has to be released by the backend, 0 otherwise
*/
int DM_release(DerivedMesh *dm);
/* utility function to convert a DerivedMesh to a Mesh
/** utility function to convert a DerivedMesh to a Mesh
*/
void DM_to_mesh(DerivedMesh *dm, struct Mesh *me, struct Object *ob);
@ -459,11 +460,10 @@ void DM_to_bmesh_ex(struct DerivedMesh *dm, struct BMesh *bm);
struct BMesh *DM_to_bmesh(struct DerivedMesh *dm);
/* utility function to convert a DerivedMesh to a shape key block
*/
/** Utility function to convert a DerivedMesh to a shape key block */
void DM_to_meshkey(DerivedMesh *dm, struct Mesh *me, struct KeyBlock *kb);
/* set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
/** set the CD_FLAG_NOCOPY flag in custom data layers where the mask is
* zero for the layer type, so only layer types specified by the mask
* will be copied
*/
@ -545,7 +545,7 @@ void DM_ensure_tessface(DerivedMesh *dm);
void DM_update_tessface_data(DerivedMesh *dm);
/* interpolates vertex data from the vertices indexed by src_indices in the
/** interpolates vertex data from the vertices indexed by src_indices in the
* source mesh using the given weights and stores the result in the vertex
* indexed by dest_index in the dest mesh
*/
@ -553,7 +553,7 @@ void DM_interp_vert_data(struct DerivedMesh *source, struct DerivedMesh *dest,
int *src_indices, float *weights,
int count, int dest_index);
/* interpolates edge data from the edges indexed by src_indices in the
/** interpolates edge data from the edges indexed by src_indices in the
* source mesh using the given weights and stores the result in the edge indexed
* by dest_index in the dest mesh.
* if weights is NULL, all weights default to 1.
@ -566,7 +566,7 @@ void DM_interp_edge_data(struct DerivedMesh *source, struct DerivedMesh *dest,
float *weights, EdgeVertWeight *vert_weights,
int count, int dest_index);
/* interpolates face data from the faces indexed by src_indices in the
/** interpolates face data from the faces indexed by src_indices in the
* source mesh using the given weights and stores the result in the face indexed
* by dest_index in the dest mesh.
* if weights is NULL, all weights default to 1.
@ -592,7 +592,7 @@ void DM_interp_poly_data(struct DerivedMesh *source, struct DerivedMesh *dest,
/* Temporary? A function to give a colorband to derivedmesh for vertexcolor ranges */
void vDM_ColorBand_store(struct ColorBand *coba);
/* Simple function to get me->totvert amount of vertices/normals,
/** Simple function to get me->totvert amount of vertices/normals,
* correctly deformed and subsurfered. Needed especially when vertexgroups are involved.
* In use now by vertex/weight paint and particles */
float *mesh_get_mapped_verts_nors(struct Scene *scene, struct Object *ob);
@ -641,13 +641,13 @@ int editbmesh_modifier_is_enabled(struct Scene *scene, struct ModifierData *md,
void makeDerivedMesh(struct Scene *scene, struct Object *ob, struct BMEditMesh *em,
CustomDataMask dataMask, int build_shapekey_layers);
/* returns an array of deform matrices for crazyspace correction, and the
/** returns an array of deform matrices for crazyspace correction, and the
* number of modifiers left */
int editbmesh_get_first_deform_matrices(struct Scene *, struct Object *, struct BMEditMesh *em,
float (**deformmats)[3][3], float (**deformcos)[3]);
void weight_to_rgb(float r_rgb[3], const float weight);
/* Update the weight MCOL preview layer.
/** Update the weight MCOL preview layer.
* If weights are NULL, use object's active vgroup(s).
* Else, weights must be an array of weight float values.
* If indices is NULL, it must be of numVerts length.
@ -657,7 +657,7 @@ void weight_to_rgb(float r_rgb[3], const float weight);
void DM_update_weight_mcol(struct Object *ob, struct DerivedMesh *dm, int const draw_flag,
float *weights, int num, const int *indices);
/* convert layers requested by a GLSL material to actually available layers in
/** convert layers requested by a GLSL material to actually available layers in
* the DerivedMesh, with both a pointer for arrays and an offset for editmesh */
typedef struct DMVertexAttribs {
struct {
@ -689,7 +689,7 @@ void DM_vertex_attributes_from_gpu(DerivedMesh *dm,
void DM_add_tangent_layer(DerivedMesh *dm);
void DM_calc_auto_bump_scale(DerivedMesh *dm);
/* Set object's bounding box based on DerivedMesh min/max data */
/** Set object's bounding box based on DerivedMesh min/max data */
void DM_set_object_boundbox(struct Object *ob, DerivedMesh *dm);
void DM_init_origspace(DerivedMesh *dm);