Yamyam: 1版をインポートしました

2018-06-28T17:50:23Z

1版をインポートしました

wiki>DBugSlayer: /* Custom Data in EditMesh */ typo

2011-04-13T03:48:10Z

‎Custom Data in EditMesh: typo

新規ページ

=Introduction=
This projects aims to allow adding of custom data to vertices, edges, faces, and
unify handling of data attached to them, like UV's and colors. This will be first
implemented for meshes, but should be general enough to also work for lattices,
NURBS, ..

Below is the code documentation on the current implementation.

[[User:Brecht|Brecht]]

=Custom Element Data=

The CustomData API provides a generic way to manipulate per-element custom data in meshes. Each unit of custom data is called a layer. Each layer is identified by a type, which has a size and a set of data-handling functions associated with it.

This makes it possible to add new data layers to meshes without making modifications all over the Blender code. Note that this API does not make it possible for external plugins or python scripts to define their own layer types. A special [[Dev:Source/Data System/ID Property|ID Property]] layer type could be implemented for that to work.

The CustomData module was implemented by [[User:Artificer|Ben Batt]] for the [[User:Artificer/ModifierStackUpgrade|Modifier Stack Upgrade]], and later extended by [[User:Brecht|Brecht Van Lommel]] for use beyond the the modifier stack and DerivedMesh. Much of the content has been taken from the modifier stack upgrade documentation.

==Functionality==

=====Storage=====
Custom Data may be stored in two ways. The first is in a separate array for each type of layer, which is used in most cases. In edit mode, the data is stored in a memory block per element. The API for the latter type of storage is more limited, as it is used only for one specific case.

=====Adding Layers=====
When adding a layer, the arrays can be allocated or assigned in different ways:
* <code>Assign</code>: assign a given pointer is used.
* <code>Calloc</code>: allocate blank memory.
* <code>Default</code>: allocate memory and set it to the default value.
* <code>Reference</code>: assign a given pointer, but don''t free it.
* <code>Duplicate</code>: duplicate the memory of a given pointer.

Besides that there are also a number of flags that can be set:
* <code>No Copy</code>: don't copy this layer, e.g. restricting the layers copied in the modifier stack.
* <code>No Free</code>: don't free the array of this layer.
* <code>Temporary</code>: for derivedmesh, layer is only temporary, and will be freed on derivedmesh release.

=====Copying and Merging=====
The API provides a way to copy or merge an existing <code>CustomData</code> struct into another, specifying a different layer size. The new layer data may be allocated with the same options as for adding layers. A mask is also provided that indicates which layer types should be or shouldn't be copied.

=====Editing Custom Data=====
For array storage reading or writing the contents of a particular layer may be done directly on the array. For reading or writing in edit mode storage, a pointer to the data for an element is returned by the API. There are also functions for copying or interpolating the data from all layers from one collection of layers to another. See the function reference

==Usage==
=====Custom Data in Mesh=====
The Mesh datablock uses the CustomData API to store all per-element layers, including the vertices, edges and faces themselfs. Adding, freeing, copying, and interpolating layers <i>must</i> be done through the CustomData API.
<source lang="cpp">
typedef struct Mesh {
...
struct MFace *mface;
struct MTFace *mtface;
struct MVert *mvert;
struct MEdge *medge;
struct MDeformVert *dvert;
struct MCol *mcol;
struct MSticky *msticky;
...
struct CustomData vdata, edata, fdata;
...
} Mesh;
</source>
A <code>CustomData</code> struct for vertices, edges and faces contains a list of data layers. The Mesh struct contains duplicates of some of the pointers to the data, and these must be kept consistent with the pointers in the <code>CustomData</code> struct at all times. Using <code>mesh_update_customdata_pointers</code> these pointers can be updated to point to the data as stored in the <code>CustomData</code> structs.

[[Image:Mesh_customdata.png|Mesh Custom Data Storage]]

=====Custom Data in DerivedMesh=====
DerivedMesh also uses the CustomData API. All DerivedMesh backends stores the data associated with vertices, edges and faces in a <code>CustomData</code> struct, but only the CDDerivedMesh backend stores the vertices, edges and faces themselves there.

=====Custom Data in EditMesh=====
EditMesh stores its custom data in blocks per <code>EditVert</code>, <code>EditEdge</code> and <code>EditFace</code>. The special <code>CustomData_em</code> functions must be used to work with custom data in edit mode.

[[Image:Editmode_customdata.png|EditMesh Custom Data Storage]]

==Internals==
=====CustomData structure=====
The CustomData structure stores a collection of custom data layers associated with a mesh element type.
<source lang="cpp">
typedef struct CustomData {
CustomDataLayer *layers; /* CustomDataLayers, ordered by type */
int totlayer, maxlayer; /* number of layers, size of layers array */
int totsize, pad; /* in editmode, total size of all data layers */
} CustomData;
</source>

=====CustomDataLayer structure=====
<source lang="cpp">
typedef struct CustomDataLayer {
int type; /* type of data in layer */
int offset; /* in editmode, offset of layer in block */
int flag; /* general purpose flag */
int active; /* number of the active layer of this type */
void *data; /* layer data */
} CustomDataLayer;
</source>

=====Layer Type Info=====
The <code>CustomDataLayer.type</code> field is passed to the <code>layerType_getInfo</code> function, where it is used as an index into the <code>LAYERTYPEINFO</code> array (an array of <code>LayerTypeInfo</code> structures). It can hold any value of any of the defined types, such as <code>CD_MVERT</code>, <code>CD_MDEFORMVERT</code> or <code>CD_MTFACE</code>.

=====LayerTypeInfo structure=====
The <code>LayerTypeInfo</code> structure holds information about a layer type, including its size and various functions which are used to access or modify it. The <code>LAYERTYPEINFO</code> array is a static array of <code>LayerTypeInfo</code> structures indexed by type ID and accessed via <code>layerType_getInfo()</code>. When a new layer type is added, a new entry must be added to this array, giving the size and data manipulation functions (if needed) for the new type.
<source lang="cpp">
typedef struct LayerTypeInfo {
int size; /* the memory size of one element of this layer's data */

/* a function to copy count elements of this layer's data
* (deep copy if appropriate)
* size should be the size of one element of this layer's data (e.g.
* LayerTypeInfo.size)
*/
void (*copy)(const void *source, void *dest, int count, int size);

/* a function to free any dynamically allocated components of this
* layer's data (note the data pointer itself should not be freed)
* size should be the size of one element of this layer's data (e.g.
* LayerTypeInfo.size)
*/
void (*free)(void *data, int count, int size);

/* a function to interpolate between count source elements of this
* layer's data and store the result in dest
* if weights == NULL or sub_weights == NULL, they should default to 1
*
* weights gives the weight for each element in sources
* sub_weights gives the sub-element weights for each element in sources
* (there should be (sub element count)^2 weights per element)
* count gives the number of elements in sources
*/
void (*interp)(void **sources, float *weights, float *sub_weights,
int count, void *dest);

/* a function to swap the data in corners of the element */
void (*swap)(void *data, int *corner_indices);

/* a function to set a layer's data to default values. if NULL, the
default is assumed to be all zeros */
void (*set_default)(void *data, int count);
} LayerTypeInfo;

const LayerTypeInfo LAYERTYPEINFO[LAYERTYPE_NUMTYPES] = {
{sizeof(MVert), NULL, NULL, NULL, NULL, NULL},
...
{sizeof(MDeformVert), "MDeformVert", 1, layerCopy_mdeformvert,
layerFree_mdeformvert, layerInterp_mdeformvert, NULL, NULL},
...
{sizeof(MTFace), "MTFace", 1, layerCopy_tface, NULL, layerInterp_tface,
layerSwap_tface, layerDefault_tface},
...
};

const LayerTypeInfo *layerType_getInfo(int type);
</source>

==Function Reference==
These functions provide a generic interface to a custom element data stack.

======void CustomData_copy======
<source lang="cpp">
void CustomData_copy(const CustomData *source, CustomData *dest,
CustomDataMask mask, int alloctype, int totelem);
</source>

Initialises a CustomData object with the same layer setup as source, and totelem elements.
* Mask is a bitfield where (mask & (1 << (layer type))) indicates if a layer should be copied or not.
* Alloctype must be one of the above.

======void CustomData_merge======
<source lang="cpp">
void CustomData_merge(const CustomData *source, CustomData *dest,
CustomDataMask mask, int alloctype, int totelem);
</source>

Same as the above, except that this will preserve existing layers, and only add the layers that were not there yet.

======void CustomData_free======
<source lang="cpp">
void CustomData_free(CustomData *data, int totelem);
</source>

Frees data associated with a CustomData object (doesn't free the object itself, though).

======void CustomData_free_temporary======
<source lang="cpp">
void CustomData_free_temporary(CustomData *data, int totelem);
</source>

Frees all layers with CD_FLAG_TEMPORARY.

======void *CustomData_add_layer======
<source lang="cpp">
void *CustomData_add_layer(CustomData *data, int type, int alloctype,
void *layer, int totelem);
</source>

Adds a data layer of the given type to the CustomData object, optionally backed by an external data array. The different allocation types are as defined above.
* Returns the data of the layer.
* In editmode, use EM_add_data_layer instead of this function.

======int CustomData_free_layer======
<source lang="cpp">
int CustomData_free_layer(CustomData *data, int type, int totelem);
</source>

Frees the active or first data layer with the give type.
* Returns 1 on succes, 0 if no layer with the given type is found
* In editmode, use EM_free_data_layer instead of this function

======void CustomData_free_layers======
<source lang="cpp">
void CustomData_free_layers(CustomData *data, int type, int totelem);
</source>

Same as above, but free all layers with type.

======int CustomData_has_layer======
<source lang="cpp">
int CustomData_has_layer(const CustomData *data, int type);
</source>

* Returns 1 if a layer with the specified type exists.

======int CustomData_number_of_layers======
<source lang="cpp">
int CustomData_number_of_layers(const CustomData *data, int type);
</source>

* Returns the number of layers with this type.

======void *CustomData_duplicate_referenced_layer======
<source lang="cpp">
void *CustomData_duplicate_referenced_layer(CustomData *data, int type);
</source>

* Duplicate data of a layer with flag CD_FLAG_NOFREE, and remove that flag.

======void CustomData_set_only_copy======
<source lang="cpp">
void CustomData_set_only_copy(const CustomData *data,
CustomDataMask mask);
</source>

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.

======void CustomData_copy_data======
<source lang="cpp">
void CustomData_copy_data(const CustomData *source,
CustomData *dest, int source_index,
int dest_index, int count);
void CustomData_em_copy_data(const CustomData *source,
CustomData *dest, void *src_block,
void **dest_block);
</source>

Copies data from one CustomData object to another objects need not be compatible, each source layer is copied to the first dest layer of correct type (if there is none, the layer is skipped).

======void CustomData_free_elem======
<source lang="cpp">
void CustomData_free_elem(CustomData *data, int index, int count);
</source>

Frees count data elements on each layer starting at index in a CustomData object.

======void CustomData_interp======
<source lang="cpp">
void CustomData_interp(const CustomData *source, CustomData *dest,
int *src_indices, float *weights, float *sub_weights,
int count, int dest_index);
void CustomData_em_interp(CustomData *data, void **src_blocks,
float *weights, float *sub_weights, int count,
void *dest_block);
</source>

Interpolates data from one CustomData object to another.
*The objects need not be compatible, each source layer is interpolated to the first dest layer of the correct type (if there is none, the layer is skipped).
*If weights == NULL or sub_weights == NULL, they default to all 1's.
*src_indices gives the source elements to interpolate from.
*weights gives the weight for each source element.
*sub_weights is an array of matrices of weights for sub-elements (matrices should be source->subElems * source->subElems in size).
*count gives the number of source elements to interpolate from.
*dest_index gives the dest element to write the interpolated value to.

======void *CustomData_get======
<source lang="cpp">
void *CustomData_get(const CustomData *data, int index, int type);
void *CustomData_em_get(const CustomData *data, void *block, int type);
</source>

Gets a pointer to the data element at index from the first or active layer of the specified type.
*Returns NULL if there is no layer of the specified type.

======void *CustomData_get_layer======
<source lang="cpp">
void *CustomData_get_layer(const CustomData *data, int type);
void *CustomData_get_layer_n(const CustomData *data, int type, int n);
</source>

Gets a pointer to the first/active or nth layer of the specified type.
*Returns NULL if there is no layer of the specified type.

======void CustomData_set======
<source lang="cpp">
void CustomData_set(const CustomData *data, int index, int type, void *source);
void CustomData_em_set(struct CustomData *data, void *block, int type,
void *source);
</source>

Copies the data from source to the data element at index in the first layer of the specified type.
*No effect if there is no layer of the specified type.

======void CustomData_set_layer*======
<source lang="cpp">
void *CustomData_set_layer(const CustomData *data, int type, void *ptr);
void CustomData_set_layer_active(CustomData *data, int type, int n);
void CustomData_set_layer_flag(CustomData *data, int type, int flag);
</source>

* Set the pointer of to the first layer of type. the old data is not freed.
* Sets the nth layer of type as active.
* Adds flag to the layer flags.

======void CustomData_to/from_em_block======
<source lang="cpp">
void CustomData_to_em_block(const CustomData *source,
CustomData *dest, int index, void **block);
void CustomData_from_em_block(const CustomData *source,
CustomData *dest, void *block, int index);
</source>

Copy to and from editmesh storage.

[[Category:Script]]

← 古い版	2018年6月28日 (木) 17:50時点における版
(相違点なし)

Dev:Source/Architecture/Custom Element Data - 版の履歴

Yamyam: 1版 をインポートしました

wiki>DBugSlayer: /* Custom Data in EditMesh */ typo

Yamyam: 1版をインポートしました