style cleanup: header comments, use more doxy compat formatting
authorCampbell Barton <ideasman42@gmail.com>
Wed, 27 Jun 2012 17:48:39 +0000 (17:48 +0000)
committerCampbell Barton <ideasman42@gmail.com>
Wed, 27 Jun 2012 17:48:39 +0000 (17:48 +0000)
intern/guardedalloc/MEM_guardedalloc.h
source/blender/blenkernel/BKE_DerivedMesh.h

index 1d0a8db6329af897b43544ecf2323a16c431bd88..4bb8cba6810ac9196fabaa003334aa08505921b0 100644 (file)
@@ -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
-
index c7ddab479520bcb9830b91de6d419efd15795b7a..64512dcaac8fa7e3588162f45ccd141fc817ab5a 100644 (file)
 #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);