From 9c964240e4a8b7e8259dd661442325a884320db1 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Thu, 15 Feb 2024 14:26:12 +0100 Subject: [PATCH 1/4] Add docs for how object's stored transforms work The main point is to document how loc/rot/scale interact with dloc/drot/dscale. But this also covers the parent-inverse matrix. --- docs/features/objects/transform.md | 36 ++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/features/objects/transform.md b/docs/features/objects/transform.md index 1a0911b7..40518436 100644 --- a/docs/features/objects/transform.md +++ b/docs/features/objects/transform.md @@ -133,3 +133,39 @@ be more or less complex. Steps in **bold** are rather mandatory. 6. **recalcData** : Flush updates to Blender data when needed 7. **headerPrint** : Send text to the header 8. **viewRedrawForce** : Send redraw events to the proper screen area + +## Stored Transforms + +Each object has a set of source-of-truth (i.e. not derived or cached) transforms stored directly in its DNA, in the `Object` struct in `DNA_object_types.h`. These specify the aspects of an object's transforms that are independent of other objects in the scene, and which do not result from constraints, etc. + +### Loc/Rot/Scale + +The simplest of these are the `loc`, `rot`, and `scale` properties, which form the base transform of an object. These are the familiar properties that users use to set and animate an object's position in 3D space. + +`rot` also has counterparts for quaternion and axis-angle rotations: `quat` for quaternions and `rotAxis` + `rotAngle` for axis-angle. These are used for the object's rotation when `rotmode` is set to the corresponding rotation mode. + +### Delta Transforms + +After the base transform, there are the delta transforms, stored in the `dloc`, `drot`, and `dscale` properties. These can also be set by the user, and effectively define a "rest position" for the object. + +`loc`/`rot`/`scale` and `dloc`/`drot`/`dscale` are combined into a whole transform as follows: + +1. `loc` and `dloc` are simply added together as vectors. +2. `rot` and `drot` are combined by first creating a 3x3 matrix for each, and then multiplying them together. The multiplication order is equivalent to first applying `rot`'s rotation to the object and then applying `drot`'s rotation. +3. `scale` and `dscale` are simply component-wise multiplied together. +4. Finally, the results of the previous steps are all combined together into a single transform matrix. + +> NOTE: +> Quaternion and axis-angle rotation modes also have corresponding `d*` properties for delta transforms, for when the object is in those respective rotation modes. They are applied the same way as `drot`. + +The relevant code for this is in `blenkernel/intern/object.cc` in the functions `BKE_object_scale_to_mat3`, `BKE_object_rot_to_mat3`, `BKE_object_to_mat3`, and `BKE_object_to_mat4`. + +### Parent-Inverse Matrix + +Finally, there is one additional transform step that is internal to an object: the parent-inverse matrix. + +The parent-inverse matrix is a 4x4 matrix stored in the property `parentinv`. Importantly, it is *not* the transform (inverse or otherwise) of the object's parent. Rather, it's an arbitrary 4x4 matrix that gets applied to an object's transforms if and only if it has a parent. + +Its intended purpose (and the source of its name) is to keep a child object where it is visually when a parent-child relationship is created, without changing the child's loc/rot/scale values. To accomplish this, the matrix is automatically set to the inverse of the parent's transform *at the time the parent-child relationship is created*. It is specifically *not* updated to continuously match the parent's inverse. + +The relevant code for this is in `blenkernel/intern/object.cc` in the function `BKE_object_apply_mat4_ex`. \ No newline at end of file -- 2.30.2 From d321398dfb8dec3096eb9c90e085969f792b067b Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Thu, 15 Feb 2024 16:57:09 +0100 Subject: [PATCH 2/4] Hard wrap text --- docs/features/objects/transform.md | 55 ++++++++++++++++++++++-------- 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/docs/features/objects/transform.md b/docs/features/objects/transform.md index 40518436..d17eb2ab 100644 --- a/docs/features/objects/transform.md +++ b/docs/features/objects/transform.md @@ -136,36 +136,63 @@ be more or less complex. Steps in **bold** are rather mandatory. ## Stored Transforms -Each object has a set of source-of-truth (i.e. not derived or cached) transforms stored directly in its DNA, in the `Object` struct in `DNA_object_types.h`. These specify the aspects of an object's transforms that are independent of other objects in the scene, and which do not result from constraints, etc. +Each object has a set of source-of-truth (i.e. not derived or cached) transforms +stored directly in its DNA, in the `Object` struct in `DNA_object_types.h`. +These specify the aspects of an object's transforms that are independent of +other objects in the scene, and which do not result from constraints, etc. ### Loc/Rot/Scale -The simplest of these are the `loc`, `rot`, and `scale` properties, which form the base transform of an object. These are the familiar properties that users use to set and animate an object's position in 3D space. +The simplest of these are the `loc`, `rot`, and `scale` properties, which form +the base transform of an object. These are the familiar properties that users +use to set and animate an object's position in 3D space. -`rot` also has counterparts for quaternion and axis-angle rotations: `quat` for quaternions and `rotAxis` + `rotAngle` for axis-angle. These are used for the object's rotation when `rotmode` is set to the corresponding rotation mode. +`rot` also has counterparts for quaternion and axis-angle rotations: `quat` for +quaternions and `rotAxis` + `rotAngle` for axis-angle. These are used for the +object's rotation when `rotmode` is set to the corresponding rotation mode. ### Delta Transforms -After the base transform, there are the delta transforms, stored in the `dloc`, `drot`, and `dscale` properties. These can also be set by the user, and effectively define a "rest position" for the object. +After the base transform, there are the delta transforms, stored in the `dloc`, +`drot`, and `dscale` properties. These can also be set by the user, and +effectively define a "rest position" for the object. -`loc`/`rot`/`scale` and `dloc`/`drot`/`dscale` are combined into a whole transform as follows: +`loc`/`rot`/`scale` and `dloc`/`drot`/`dscale` are combined into a whole +transform as follows: 1. `loc` and `dloc` are simply added together as vectors. -2. `rot` and `drot` are combined by first creating a 3x3 matrix for each, and then multiplying them together. The multiplication order is equivalent to first applying `rot`'s rotation to the object and then applying `drot`'s rotation. +2. `rot` and `drot` are combined by first creating a 3x3 matrix for each, and + then multiplying them together. The multiplication order is equivalent to + first applying `rot`'s rotation to the object and then applying `drot`'s + rotation. 3. `scale` and `dscale` are simply component-wise multiplied together. -4. Finally, the results of the previous steps are all combined together into a single transform matrix. +4. Finally, the results of the previous steps are all combined together into a + single transform matrix. -> NOTE: -> Quaternion and axis-angle rotation modes also have corresponding `d*` properties for delta transforms, for when the object is in those respective rotation modes. They are applied the same way as `drot`. +> NOTE: Quaternion and axis-angle rotation modes also have corresponding `d*` +> properties for delta transforms, for when the object is in those respective +> rotation modes. They are applied the same way as `drot`. -The relevant code for this is in `blenkernel/intern/object.cc` in the functions `BKE_object_scale_to_mat3`, `BKE_object_rot_to_mat3`, `BKE_object_to_mat3`, and `BKE_object_to_mat4`. +The relevant code for this is in `blenkernel/intern/object.cc` in the functions +`BKE_object_scale_to_mat3`, `BKE_object_rot_to_mat3`, `BKE_object_to_mat3`, and +`BKE_object_to_mat4`. ### Parent-Inverse Matrix -Finally, there is one additional transform step that is internal to an object: the parent-inverse matrix. +Finally, there is one additional transform step that is internal to an object: +the parent-inverse matrix. -The parent-inverse matrix is a 4x4 matrix stored in the property `parentinv`. Importantly, it is *not* the transform (inverse or otherwise) of the object's parent. Rather, it's an arbitrary 4x4 matrix that gets applied to an object's transforms if and only if it has a parent. +The parent-inverse matrix is a 4x4 matrix stored in the property `parentinv`. +Importantly, it is *not* the transform (inverse or otherwise) of the object's +parent. Rather, it's an arbitrary 4x4 matrix that gets applied to an object's +transforms if and only if it has a parent. -Its intended purpose (and the source of its name) is to keep a child object where it is visually when a parent-child relationship is created, without changing the child's loc/rot/scale values. To accomplish this, the matrix is automatically set to the inverse of the parent's transform *at the time the parent-child relationship is created*. It is specifically *not* updated to continuously match the parent's inverse. +Its intended purpose (and the source of its name) is to keep a child object +where it is visually when a parent-child relationship is created, without +changing the child's loc/rot/scale values. To accomplish this, the matrix is +automatically set to the inverse of the parent's transform *at the time the +parent-child relationship is created*. It is specifically *not* updated to +continuously match the parent's inverse. -The relevant code for this is in `blenkernel/intern/object.cc` in the function `BKE_object_apply_mat4_ex`. \ No newline at end of file +The relevant code for this is in `blenkernel/intern/object.cc` in the function +`BKE_object_apply_mat4_ex`. \ No newline at end of file -- 2.30.2 From dbac7ff49057c98586606a4b27fec9cce3e498a6 Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Thu, 15 Feb 2024 17:14:00 +0100 Subject: [PATCH 3/4] Be more succinct about delta transforms --- docs/features/objects/transform.md | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/docs/features/objects/transform.md b/docs/features/objects/transform.md index d17eb2ab..cac48589 100644 --- a/docs/features/objects/transform.md +++ b/docs/features/objects/transform.md @@ -137,7 +137,7 @@ be more or less complex. Steps in **bold** are rather mandatory. ## Stored Transforms Each object has a set of source-of-truth (i.e. not derived or cached) transforms -stored directly in its DNA, in the `Object` struct in `DNA_object_types.h`. +stored directly in its DNA, in the `Object` struct in *DNA_object_types.h*. These specify the aspects of an object's transforms that are independent of other objects in the scene, and which do not result from constraints, etc. @@ -157,23 +157,15 @@ After the base transform, there are the delta transforms, stored in the `dloc`, `drot`, and `dscale` properties. These can also be set by the user, and effectively define a "rest position" for the object. -`loc`/`rot`/`scale` and `dloc`/`drot`/`dscale` are combined into a whole -transform as follows: - -1. `loc` and `dloc` are simply added together as vectors. -2. `rot` and `drot` are combined by first creating a 3x3 matrix for each, and - then multiplying them together. The multiplication order is equivalent to - first applying `rot`'s rotation to the object and then applying `drot`'s - rotation. -3. `scale` and `dscale` are simply component-wise multiplied together. -4. Finally, the results of the previous steps are all combined together into a - single transform matrix. +`loc`/`dloc`, `rot`/`drot`, and `scale`/`dscale` are first combined as pairs +(e.g. `loc` with `dloc`), and then assembled together into a transform matrix +afterward. > NOTE: Quaternion and axis-angle rotation modes also have corresponding `d*` > properties for delta transforms, for when the object is in those respective > rotation modes. They are applied the same way as `drot`. -The relevant code for this is in `blenkernel/intern/object.cc` in the functions +The relevant code for this is in *blenkernel/intern/object.cc* in the functions `BKE_object_scale_to_mat3`, `BKE_object_rot_to_mat3`, `BKE_object_to_mat3`, and `BKE_object_to_mat4`. @@ -194,5 +186,5 @@ automatically set to the inverse of the parent's transform *at the time the parent-child relationship is created*. It is specifically *not* updated to continuously match the parent's inverse. -The relevant code for this is in `blenkernel/intern/object.cc` in the function -`BKE_object_apply_mat4_ex`. \ No newline at end of file +The relevant code for applying this transform is in *blenkernel/intern/object.cc* in the function +`BKE_object_apply_mat4_ex`. -- 2.30.2 From 711a6937d8abd558fa06589fd158e5394a48214b Mon Sep 17 00:00:00 2001 From: Nathan Vegdahl Date: Thu, 15 Feb 2024 17:18:30 +0100 Subject: [PATCH 4/4] Somehow missed a line when rewrapping --- docs/features/objects/transform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/objects/transform.md b/docs/features/objects/transform.md index cac48589..f6f9182c 100644 --- a/docs/features/objects/transform.md +++ b/docs/features/objects/transform.md @@ -186,5 +186,5 @@ automatically set to the inverse of the parent's transform *at the time the parent-child relationship is created*. It is specifically *not* updated to continuously match the parent's inverse. -The relevant code for applying this transform is in *blenkernel/intern/object.cc* in the function -`BKE_object_apply_mat4_ex`. +The relevant code for applying this transform is in +*blenkernel/intern/object.cc* in the function `BKE_object_apply_mat4_ex`. -- 2.30.2