Add docs for how object's stored transforms work #23

Merged
Nathan Vegdahl merged 4 commits from nathanvegdahl/blender-developer-docs:stored_object_transforms into main 2024-11-25 10:42:54 +01:00
Member

The main point is to document how loc/rot/scale interact with
dloc/drot/dscale. But this also covers the parent-inverse matrix.

The main point is to document how loc/rot/scale interact with dloc/drot/dscale. But this also covers the parent-inverse matrix.
Nathan Vegdahl added 1 commit 2024-02-15 14:34:55 +01:00
The main point is to document how loc/rot/scale interact with
dloc/drot/dscale.  But this also covers the parent-inverse matrix.
Author
Member

My main questions:

  1. Is this the right section to put this documentation in?
  2. Is there a better term to use than "stored transforms"? The distinction I'm trying to make is between the base, source-of-truth transforms of an object vs those that result from applying parenting, constraints, etc. Not sure if we already have a term for that.
My main questions: 1. Is this the right section to put this documentation in? 2. Is there a better term to use than "stored transforms"? The distinction I'm trying to make is between the base, source-of-truth transforms of an object vs those that result from applying parenting, constraints, etc. Not sure if we already have a term for that.
Member

Nice to have documentation like this! Two thoughts:

  • I think the lines are meant to be wrapper at 100 (?) characters or so, that just makes editing a bit easier I guess.
  • Personally I find the text about how the different properties are combined with the delta properties a bit too details for the docs. They read more like a description of a function in the code. In that case the function itself should be well documented and easy to read. It might be better to sum it up in a sentence or two and then refer readers to the function docs/implementation for more detail.
Nice to have documentation like this! Two thoughts: - I think the lines are meant to be wrapper at 100 (?) characters or so, that just makes editing a bit easier I guess. - Personally I find the text about how the different properties are combined with the delta properties a bit too details for the docs. They read more like a description of a function in the code. In that case the function itself should be well documented and easy to read. It might be better to sum it up in a sentence or two and then refer readers to the function docs/implementation for more detail.
Author
Member

It might be better to sum it up in a sentence or two and then refer readers to the function docs/implementation for more detail.

That's fair, yeah. In this case, I documented it because that specific question came up when we were trying to make a related decision, and it ended up being a bit annoying to track down. But the main challenge was finding the relevant functions. So I can just summarize "the components are combined individually before being assembled into a matrix" and then point to the relevant functions for when more details are needed.

I think the lines are meant to be wrapper at 100 (?) characters or so

Oh! I didn't realize that. For prose I personally find that hard wrapping actually makes editing harder, since I always edit prose with word wrapping on anyway. And hard wrapping just means I have to take the extra step to re-wrap things after I've made edits. But if that's already been decided, I'm happy to adhere.

> It might be better to sum it up in a sentence or two and then refer readers to the function docs/implementation for more detail. That's fair, yeah. In this case, I documented it because that specific question came up when we were trying to make a related decision, and it ended up being a bit annoying to track down. But the main challenge was finding the relevant functions. So I can just summarize "the components are combined individually before being assembled into a matrix" and then point to the relevant functions for when more details are needed. > I think the lines are meant to be wrapper at 100 (?) characters or so Oh! I didn't realize that. For prose I personally find that hard wrapping actually makes editing harder, since I always edit prose with word wrapping on anyway. And hard wrapping just means I have to take the extra step to re-wrap things after I've made edits. But if that's already been decided, I'm happy to adhere.
Member

So I can just summarize "the components are combined individually before being assembled into a matrix" and then point to the relevant functions for when more details are needed.

Thanks, sounds great!

For prose I personally find that hard wrapping actually makes editing harder, since I always edit prose with word wrapping on anyway

Yeah, it's not easier for me either TBH. But it's nice to be consistent.

> So I can just summarize "the components are combined individually before being assembled into a matrix" and then point to the relevant functions for when more details are needed. Thanks, sounds great! > For prose I personally find that hard wrapping actually makes editing harder, since I always edit prose with word wrapping on anyway Yeah, it's not easier for me either TBH. But it's nice to be consistent.
Member
  • I think the lines are meant to be wrapper at 100 (?) characters or so, that just makes editing a bit easier I guess.

We indeed use a 100 character (actually 99) limit, see style guide. It seems like people expect a line limit, it kept coming up as question. Maybe relying on editor line wrapping is fine, but I'd hope that auto-formatting takes away any effort either way. That's why we have the .editorconfig in place now.

> - I think the lines are meant to be wrapper at 100 (?) characters or so, that just makes editing a bit easier I guess. We indeed use a 100 character (actually 99) limit, see [style guide](https://developer.blender.org/docs/contribute/markdown_style_guide/). It seems like people expect a line limit, it kept coming up as question. Maybe relying on editor line wrapping is fine, but I'd hope that auto-formatting takes away any effort either way. That's why we have the `.editorconfig` in place now.
Nathan Vegdahl added 1 commit 2024-02-15 16:57:40 +01:00
Nathan Vegdahl added 1 commit 2024-02-15 17:14:25 +01:00
Nathan Vegdahl added 1 commit 2024-02-15 17:18:52 +01:00
Author
Member

I've addressed the comments now.

Note that I wrapped to less than 100 characters for consistency, since the rest of this file does as well. (I somehow just didn't notice that it was hard wrapped at all before.)

That's why we have the .editorconfig in place now.

Not relevant to this PR, but the official EditorConfig extension for VSCode doesn't appear to support the max_line_length config option, which is annoying.

I've addressed the comments now. Note that I wrapped to less than 100 characters for consistency, since the rest of this file does as well. (I somehow just didn't notice that it was hard wrapped at all before.) > That's why we have the `.editorconfig` in place now. Not relevant to this PR, but the official [EditorConfig extension for VSCode](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) doesn't appear to support the `max_line_length` config option, which is annoying.
Hans Goudey approved these changes 2024-11-22 19:21:18 +01:00
Hans Goudey left a comment
Member

Would be nice to add this to the docs!

Would be nice to add this to the docs!
Nathan Vegdahl merged commit 2176472a9d into main 2024-11-25 10:42:54 +01:00
Nathan Vegdahl deleted branch stored_object_transforms 2024-11-25 10:42:55 +01:00
Sign in to join this conversation.
No reviewers
No Label
No Milestone
No Assignees
3 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: blender/blender-developer-docs#23
No description provided.