diff options
author | Hans Goudey <h.goudey@me.com> | 2021-12-26 00:08:38 +0300 |
---|---|---|
committer | Hans Goudey <h.goudey@me.com> | 2021-12-26 00:08:38 +0300 |
commit | dd3a72f275b3dfed3c6529d7ede48875149dc186 (patch) | |
tree | 1881e5a8ccdc9cbed4c325476c40bf7c2bc1a223 /source/blender/blenkernel/BKE_attribute_access.hh | |
parent | ceed8f7c06bab30913f1469503e62badfc6e2e6f (diff) |
Docs: Add to and cleanup attribute API docs
Most of the comment block is similar to the text in the source
code documentation wiki. It's helpful to have some text in
a header file too, so it's closer for programmers already looking
at the code.
This also uses more consistent syntax and wording in the comments
about the attribute API in `GeometryComponent`.
Ref T93753
Differential Revision: https://developer.blender.org/D13661
Diffstat (limited to 'source/blender/blenkernel/BKE_attribute_access.hh')
-rw-r--r-- | source/blender/blenkernel/BKE_attribute_access.hh | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/source/blender/blenkernel/BKE_attribute_access.hh b/source/blender/blenkernel/BKE_attribute_access.hh index ae9969aae82..114d9e1e0d7 100644 --- a/source/blender/blenkernel/BKE_attribute_access.hh +++ b/source/blender/blenkernel/BKE_attribute_access.hh @@ -30,6 +30,39 @@ #include "BLI_float3.hh" #include "BLI_function_ref.hh" +/** + * This file defines classes that help to provide access to attribute data on a #GeometryComponent. + * The API for retrieving attributes is defined in `BKE_geometry_set.hh`, but this comment has some + * general comments about the system. + * + * Attributes are stored in geometry data, though they can also be stored in instances. Their + * storage is often tied to `CustomData`, which is a system to store "layers" of data with specific + * types and names. However, since `CustomData` was added to Blender before attributes were + * conceptualized, it combines the "legacy" style of task-specific attribute types with generic + * types like "Float". The attribute API here only provides access to generic types. + * + * Attributes are retrieved from geometry components by providing an "id" (#AttributeIDRef). This + * is most commonly just an attribute name. The attribute API on geometry components has some more + * advanced capabilities: + * 1. Read-only access: With a `const` geometry component, an attribute on the geometry cannot be + * modified, so the `for_write` and `for_output` versions of the API are not available. This is + * extremely important for writing coherent bug-free code. When an attribute is retrieved with + * write access, via #WriteAttributeLookup or #OutputAttribute, the geometry component must be + * tagged to clear caches that depend on the changed data. + * 2. Domain interpolation: When retrieving an attribute, a domain (#AttributeDomain) can be + * provided. If the attribute is stored on a different domain and conversion is possible, a + * version of the data interpolated to the requested domain will be provided. These conversions + * are implemented in each #GeometryComponent by `attribute_try_adapt_domain_impl`. + * 3. Implicit type conversion: In addition to interpolating domains, attribute types can be + * converted, using the conversions in `BKE_type_conversions.hh`. The #VArray / #GVArray system + * makes it possible to only convert necessary indices on-demand. + * 4. Anonymous attributes: The "id" used to look up an attribute can also be an anonymous + * attribute reference. Currently anonymous attributes are only used in geometry nodes. + * 5. Abstracted storage: Since the data returned from the API is usually a virtual array, + * it doesn't have to be stored contiguously (even though that is generally preferred). This + * allows accessing "legacy" attributes like `material_index`, which is stored in `MPoly`. + */ + namespace blender::bke { /** |