Difference between revisions of "Viewer coordinate frames"

From Second Life Wiki
Jump to navigation Jump to search
m (→‎Conversion functions: Added some better styling)
 
(17 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{Multi-lang}}
{{ViewerArchNav}}
{{ViewerArchNav}}


Line 7: Line 8:


=== Global ===
=== Global ===
Absolute global coordinate frame, expressed using F64's.  This is derived from the U32 x and y coords of the handles of regions, plus the region offset.  Precise enough for ~1x10e9 regions on an edge with same precision as region-local coordinates.
Absolute global coordinate frame, expressed using F64's.  This is derived from the U32 x and y coords of the handles of regions, plus the region offset.  Precise enough for ~10<sup>9</sup> regions on an edge with same precision as region-local coordinates.


=== Region ===
=== {{Anchor|region-local|Region}} ===
Origin is the origin of the region which "owns" the object.
''Also called region-local.''<br/>
Origin is the origin of the [[Land#Region|region]] which "owns" the object.


=== Agent ===
=== Agent ===
Line 18: Line 20:
Currently a catch-all for coordinate frames which are not one of the ones above.  Generally object-relative positioning.
Currently a catch-all for coordinate frames which are not one of the ones above.  Generally object-relative positioning.


The local frame is used in two ways in [[LSL]]:
:<h4> Child Prims </h4>
:Child prims (not root prims) are positioned local to the root prim; their global position and angle affected by both the root prim's rotation and position.
:<h4> Attachments </h4>
:Objects that are attached are positioned local to the attach point; their global position and angle are affected by the position and rotation of the avatar and the playing animations{{Footnote|Playing animations don't affect the positions and rotations returned or used by LSL, they only affect how the viewer displays the position of the attachments.}}.


 
= Naming conventions =
== Naming conventions ==
ALL variables/class members dealing with values in one of these coordinate frames should be post-fixed appended with the coordinate frame that it's being used in.  PLEASE do this - it greatly reduces errors.
ALL variables/class members dealing with values in one of these coordinate frames should be post-fixed appended with the coordinate frame that it's being used in.  PLEASE do this - it greatly reduces errors.


Line 30: Line 36:
</pre>
</pre>


== Conversion functions ==
= Conversion functions =
In LLAgent and LLViewerRegion there are conversion functions for converting from one coordinate frame to the other.  They have syntax of the form getPos<target>From<source() - i.e. getPosAgentFromGlobal() converts from the global coordinate frame to the agent coordinate frame.
In <code>LLAgent</code> and <code>LLViewerRegion</code> there are conversion functions for converting from one coordinate frame to the other.  They have syntax of the form <code>getPos&lt;target>From&lt;source>()</code> - i.e. <code>getPosAgentFromGlobal()</code> converts from the global coordinate frame to the agent coordinate frame.


 
= Type conversion =
== Type conversion ==
In order to support the high-precision global coordinates, there is a new class LLVector3d, standing for LLVector3, double precision.  It's somewhat inconsistent, but the only other alternative was renaming ALL of the math classes to use the GL style last-letter type convention, which I wasn't up to doing.
In order to support the high-precision global coordinates, there is a new class LLVector3d, standing for LLVector3, double precision.  It's somewhat inconsistent, but the only other alternative was renaming ALL of the math classes to use the GL style last-letter type convention, which I wasn't up to doing.


Line 40: Line 45:




The LLVector3d class DELIBERATELY does not have ANY for of automatic type-conversion between it and the LLVector3 class.  Since conversion back and forth isn't cheap (and potentially loses precision), you have to explicitly do a setVec() on the other class to convert back and forth.
The LLVector3d class DELIBERATELY does not have ANY form of automatic type-conversion between it and the LLVector3 class.  Since conversion back and forth isn't cheap (and potentially loses precision), you have to explicitly do a setVec() on the other class to convert back and forth.
 
= Footnotes =
{{Footnotes}}

Latest revision as of 11:53, 10 June 2023

Coordinate frames

There are currently four different reference frames which are being used on the viewer. Note that there are a couple of cases in the code which do NOT follow this convention on the viewer: The rendering code uses "World" and "W" for Agent, and some of the character/joint code doesn't have a coordinate frame specified, but is specified in Agent. Also, common libraries (LLCamera and LLPrimitive in particular) do NOT use this convention. Be particularly careful when pulling values directly out of these.

Global

Absolute global coordinate frame, expressed using F64's. This is derived from the U32 x and y coords of the handles of regions, plus the region offset. Precise enough for ~109 regions on an edge with same precision as region-local coordinates.

Also called region-local.
Origin is the origin of the region which "owns" the object.

Agent

Currently, the origin is the origin of the agent's current region. THIS DOES NOT necessarily have to be the case in the future. This should be used only for code involving rendering (pipeline, visibility/frustum calculations)

Local

Currently a catch-all for coordinate frames which are not one of the ones above. Generally object-relative positioning.

The local frame is used in two ways in LSL:

Child Prims

Child prims (not root prims) are positioned local to the root prim; their global position and angle affected by both the root prim's rotation and position.

Attachments

Objects that are attached are positioned local to the attach point; their global position and angle are affected by the position and rotation of the avatar and the playing animations[1].

Naming conventions

ALL variables/class members dealing with values in one of these coordinate frames should be post-fixed appended with the coordinate frame that it's being used in. PLEASE do this - it greatly reduces errors.

For example:

mPositionGlobal, pos_global
mPositionRegion, pos_region
mPositionAgent, pos_agent

Conversion functions

In LLAgent and LLViewerRegion there are conversion functions for converting from one coordinate frame to the other. They have syntax of the form getPos<target>From<source>() - i.e. getPosAgentFromGlobal() converts from the global coordinate frame to the agent coordinate frame.

Type conversion

In order to support the high-precision global coordinates, there is a new class LLVector3d, standing for LLVector3, double precision. It's somewhat inconsistent, but the only other alternative was renaming ALL of the math classes to use the GL style last-letter type convention, which I wasn't up to doing.

ALL math being done in global coordinates should be done using LLVector3ds. Currently, all functions which return global coordinates do so in LLVector3ds. The ONLY current exception to this is audio, which I am converting to regular LLVector3s before handing them off to the audio engine - I guess this will be the case until we convert the audio engine to use agent coords.


The LLVector3d class DELIBERATELY does not have ANY form of automatic type-conversion between it and the LLVector3 class. Since conversion back and forth isn't cheap (and potentially loses precision), you have to explicitly do a setVec() on the other class to convert back and forth.

Footnotes

  1. ^ Playing animations don't affect the positions and rotations returned or used by LSL, they only affect how the viewer displays the position of the attachments.