From e727ffbadc9f9dd932964624ff6ce543385d704d Mon Sep 17 00:00:00 2001 From: Alexander Gavrilov Date: Mon, 17 Jul 2023 02:01:59 +0300 Subject: [PATCH] Driver Variables: document camera.location vs camera.matrix_world. Blender 3.6 introduced context property variables for drivers, which allow context-dependent access to the active scene or view layer without an explicit reference to a specific scene. This also allows access to the active camera via a Scene property. One major use case for this is accessing the camera transformation for various potential uses like automatic level of detail. However, the documentation isn't completely clear on how to access the evaluated transformation, as opposed to the raw animation channels before constraints and parenting. This aims do fix that oversight by making some wording more clear, and providing an easily understandable explanation of world_matrix. --- manual/animation/drivers/drivers_panel.rst | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/manual/animation/drivers/drivers_panel.rst b/manual/animation/drivers/drivers_panel.rst index 0ba48145b..87dda7594 100644 --- a/manual/animation/drivers/drivers_panel.rst +++ b/manual/animation/drivers/drivers_panel.rst @@ -138,8 +138,8 @@ Variable Type The ID of the ID-block type. For example: "Material.001". RNA Path The RNA name of the property, based on a subset of Python attribute access syntax. - For example: ``location.x`` or ``location[0]`` for the raw X location value, or - ``["prop_name"]`` for a custom property. + For example: ``location.x`` or ``location[0]`` for the X location animation channel + value (before parenting or constraints), or ``["prop_name"]`` for a custom property. .. tip:: @@ -185,8 +185,19 @@ Variable Type RNA Path The RNA name of the property, based on a subset of Python attribute access syntax. - For example: ``location.x`` or ``location[0]`` for the raw X location value, or - ``["prop_name"]`` for a custom property. + For example: ``camera.location.x`` or ``camera.location[0]`` for the camera X location animation + channel value (before parenting or constraints), or ``["prop_name"]`` for a custom property. + + .. tip:: + Although the values of the x/y/z animation channels for the camera location can be accessed + via ``camera.location[0/1/2]``, retrieving its world space location and orientation after parenting + and constraints currently requires using ``camera.matrix_world``. This property can be understood + easily by viewing the matrix as an array of four vectors in *World* space: + + * ``matrix_world[0][0/1/2]`` is the *Screen Right* direction vector (camera local X). + * ``matrix_world[1][0/1/2]`` is the *Screen Up* direction vector (camera local Y). + * ``matrix_world[2][0/1/2]`` is the **opposite** of the direction the camera is pointing. + * ``matrix_world[3][0/1/2]`` is the *location* of the camera. Value Shows the value of the variable. -- 2.30.2