Class TRayCollision

Description
Hierarchy
Nested Types
Fields
Methods

Unit

CastleTransform

Declaration

type TRayCollision = class(specialize TStructList<TRayCollisionNode>)

Description

Represents a ray collision with TCastleTransform (TCastleTransform that may have parents).

We advise to access the useful information using only the Transform or Info methods or read Distance field.

Everything else is somewhat internal information and things get complicated if you try to make sense of it. It's a TODO: to maybe deprecate this structure in favor of something simpler.

The full description is that this is a list, from the innermost TCastleTransform that was hit by the ray, to the root of the TCastleTransform tree. The First item is the collision information with the final TCastleTransform. The rest of items are parent, grandparent etc. of this TCastleTransform object (so it is a path within TCastleViewport.Items hierarchy tree).

But be aware that CGE uses some internal TCastleTransform instances. E.g. TCastleBox, TCastleTiledMap have internal TCastleScene instances. These internal components are marked with csTransient flag in ComponentState.

We, again, advise to not iterate over this list or access e.g. first item directly. Use only Transform or Info methods or read Distance field! Things are simple then.

This is never an empty list when returned by RayCollision.

Source: transform/castletransform_initial_types.inc (line 153).

Hierarchy

Show Additional Members:

Overview

Nested Types

Public PtrT = ˆT;
Public PTypeList = ˆTTypeList;
Public TTypeList = array [0 .. MaxInt div SizeOf(T) - 1] of T;

Fields

Public Distance: Single;

Methods

Public function List: PTypeList; deprecated 'use L, like MyList.L[123] instead of MyList.Listˆ[123]';
Public function L: PtrT;
Public function Add: PtrT; overload;
Public function Ptr(const I: TListSize): PtrT;
Public procedure Assign(const Source: TStructList ); overload;
Public procedure Assign(const A: array of T); overload;
Public function ItemSize: TListSize;
Public procedure AddSubRange(const Source: TStructList ; const Index, AddCount: TListSize);
Public procedure AssignLerpRange(const Fraction: Single; const V1, V2: TStructList ; const Index1, Index2, ACount: TListSize); virtual;
Public procedure AssignLerp(const Fraction: Single; const V1, V2: TStructList );
Public function PerfectlyEquals( const SecondValue: TStructList): Boolean;
Public procedure AddArray(const A: array of T); deprecated 'use AddRange';
Public procedure AddList(const Source: TStructList ); deprecated 'use AddRange';
Public procedure AssignArray(const A: array of T); deprecated 'use Assign';
Public function IndexOfItem(const Item: TCastleTransform): Integer; overload;
Public function IndexOfItem(const ItemClass: TCastleTransformClass): Integer; overload;
Public function Transform: TCastleTransform;
Public function Info(out HitInfo: TRayCollisionNode): Boolean;

Description

Nested Types

Public PtrT = ˆT;

This item is declared in ancestor TStructList.

This item has no description.

Source: base/castleutils_struct_list.inc (line 30).

Public PTypeList = ˆTTypeList;

This item is declared in ancestor TStructList.

This item has no description.

Source: base/castleutils_struct_list.inc (line 37).

Public TTypeList = array [0 .. MaxInt div SizeOf(T) - 1] of T;

This item is declared in ancestor TStructList.

TODO: Can we calculate better size on Delphi? Now we just assume that T has max size 16 * 16. This declaration will fail if you try to use TStructList with larger T. Note: we cannot declare list size too small, or using it may fail with range check error (e.g. Delphi, in IndexedPolygons_TrianglesCount, testcase: build_3d_object_by_code_2_tunnel.

Source: base/castleutils_struct_list.inc (line 36).

Fields

Public Distance: Single;

Distance, in world coordinate system, from the current camera to the picked point. The suggested usage is to decide if player is close enough to reach the 3D object — for example, you may not want to allow player to open a door by clicking on it from a far distance.

If the ray hit empty space, the distance is MaxSingle. Such case may occur because, once TCastleTransform handles TCastleTransform.PointingDevicePress, we make sure to inform it about PointingDeviceMove and PointingDeviceRelease, regardless if ray still hits this TCastleTransform instance.

Source: transform/castletransform_initial_types.inc (line 165).

Methods

Public function List: PTypeList; deprecated 'use L, like MyList.L[123] instead of MyList.Listˆ[123]';

This item is declared in ancestor TStructList.

Warning: this symbol is deprecated: use L, like MyList.L[123] instead of MyList.Listˆ[123]

Access the list contents through a pointer to an array of items.

This is exactly the same pointer as L, but the type is different: List points to an array of items, while L points to a single item.

Using L is preferred over this List, because L avoids "fake infinite list" type TTypeList, that in particular on Delphi may have too small size (and cause range check errors).

See the L description for a more detailed explanation and example.

See also
L
Access the list contents through a pointer, to get or set them efficiently.

Source: base/castleutils_struct_list.inc (line 51).

Public function L: PtrT;

This item is declared in ancestor TStructList.

Access the list contents through a pointer, to get or set them efficiently.

Use this to directly access a list value, like this: 

MyIntList.L[I] := 123;
// Equivalent but less efficient to syntax without L:
// MyIntList[I] := 123;

MyIntList.L[I] := MyIntList.L[I] + 123;
// Equivalent but less efficient to syntax without L:
// MyIntList[I] := MyIntList[I] + 123;

MyRecordList.L[I].MyField := 123;
// Never use syntax without L (see below for reasons):
// MyRecordList[I].MyField := 123; //< never do this!

The above examples of L work only in FPC ObjFpc mode or in Delphi with pointermath "on" (see https://docwiki.embarcadero.com/RADStudio/Sydney/en/Pointer_Math_(Delphi) ). These are CGE default settings when being compiled with FPC or Delphi, so you can depend on them at least in CGE implementation. Note that Delphi code using this doesn't need to be compiled with pointermath "on", it is enough that this unit is compiled with pointermath "on" and then one can use math on PtrT.

This is in particular useful if you have a list of records and you would like to set their fields. E.g. this is incorrect (and should not even compile if MyField is really a simple field): 

type
  TMyRecord = record MyField: Integer; end;
  TMyRecordList = specialize TGenericStructList<TMyRecord>;
var
  MyList: TMyRecordList;
begin
  // ...
  MyList[I].MyField := 123;

It will not work OK because you would modify only a temporary record returned by the MyList[I] getter.

In contrast, this will work OK: 

MyList.L[I].MyField := 123;

Using L is preferred over this List, because it avoids "fake infinite list" type TTypeList, that in particular on Delphi may have too small size.

See also
List
Access the list contents through a pointer to an array of items.

Source: base/castleutils_struct_list.inc (line 108).

Public function Add: PtrT; overload;

This item is declared in ancestor TStructList.

Increase Count and return pointer to new item. Comfortable and efficient way to add a new item that you want to immediately initialize.

Source: base/castleutils_struct_list.inc (line 118).

Public function Ptr(const I: TListSize): PtrT;

This item is declared in ancestor TStructList.

Pointer to ith item.

Source: base/castleutils_struct_list.inc (line 121).

Public procedure Assign(const Source: TStructList ); overload;

This item is declared in ancestor TStructList.

This item has no description.

Source: base/castleutils_struct_list.inc (line 123).

Public procedure Assign(const A: array of T); overload;

This item is declared in ancestor TStructList.

This item has no description.

Source: base/castleutils_struct_list.inc (line 124).

Public function ItemSize: TListSize;

This item is declared in ancestor TStructList.

This item has no description.

Source: base/castleutils_struct_list.inc (line 126).

Public procedure AddSubRange(const Source: TStructList ; const Index, AddCount: TListSize);

This item is declared in ancestor TStructList.

Add a subrange of another list here.

This method may ignore the OnNotify mechanism, for the sake of fast execution.

Source: base/castleutils_struct_list.inc (line 131).

Public procedure AssignLerpRange(const Fraction: Single; const V1, V2: TStructList ; const Index1, Index2, ACount: TListSize); virtual;

This item is declared in ancestor TStructList.

Assign here a linear interpolation of two other arrays. We take ACount items, from V1[Index1 ... Index1 + ACount - 1] and V2[Index2 ... Index2 + ACount - 1], and interpolate between them.

It's Ok for both V1 and V2 to be the same objects. But their ranges should not overlap, for future optimizations.

Exceptions raised
ELinearInterpolationImpossible
On classes where linear interpolation is not possible, e.g. we cannot linearly interpolate lists of strings.

Source: base/castleutils_struct_list.inc (line 143).

Public procedure AssignLerp(const Fraction: Single; const V1, V2: TStructList );

This item is declared in ancestor TStructList.

Assign linear interpolation between two other arrays.

Exceptions raised
EListsDifferentCount
If V1 and V2 have different count.
ELinearInterpolationImpossible
On classes where linear interpolation is not possible, e.g. we cannot linearly interpolate lists of strings.

Source: base/castleutils_struct_list.inc (line 151).

Public function PerfectlyEquals( const SecondValue: TStructList): Boolean;

This item is declared in ancestor TStructList.

Does the SecondValue have equal type, length and content. The values are compared perfectly, without any tolerance for difference.

Source: base/castleutils_struct_list.inc (line 156).

Public procedure AddArray(const A: array of T); deprecated 'use AddRange';

This item is declared in ancestor TStructList.

Warning: this symbol is deprecated: use AddRange

This item has no description.

Source: base/castleutils_struct_list.inc (line 159).

Public procedure AddList(const Source: TStructList ); deprecated 'use AddRange';

This item is declared in ancestor TStructList.

Warning: this symbol is deprecated: use AddRange

This item has no description.

Source: base/castleutils_struct_list.inc (line 160).

Public procedure AssignArray(const A: array of T); deprecated 'use Assign';

This item is declared in ancestor TStructList.

Warning: this symbol is deprecated: use Assign

This item has no description.

Source: base/castleutils_struct_list.inc (line 161).

Public function IndexOfItem(const Item: TCastleTransform): Integer; overload;

Index of node with given Item, -1 if none.

Source: transform/castletransform_initial_types.inc (line 168).

Public function IndexOfItem(const ItemClass: TCastleTransformClass): Integer; overload;

Index of node with given ItemClass, -1 if none.

Source: transform/castletransform_initial_types.inc (line 171).

Public function Transform: TCastleTransform;

TCastleTransform that was hit by given ray.

To be precise, this returns the inner-most TCastleTransform in the TCastleTransform tree, except it doesn't return internal TCastleTransform (that has csTransient flag in ComponentState). This way it doesn't return internal components, like internal TCastleScene inside TCastleBox or TCastleTiledMap.

Returns Nil if nothing was hit (Count is zero).

Source: transform/castletransform_initial_types.inc (line 183).

Public function Info(out HitInfo: TRayCollisionNode): Boolean;

Returns information about what was hit by given ray.

To be precise, this returns the first TRayCollisionNode on the list except it doesn't return TRayCollisionNode that relates to internal TCastleTransform (that has csTransient flag is ComponentState). This way it doesn't return internal components, like internal TCastleScene inside TCastleBox or TCastleTiledMap.

Returned HitInfo (TRayCollisionNode) is a record, which proved to be more comfortable in this case. So (unlike a class instance) you don't need to worry "who will free it" or "if it's Nil".

Returns False if nothing was hit (so Count is zero or all items are internal TCastleTransform instances). HitInfo is undefined in this case.

Source: transform/castletransform_initial_types.inc (line 201).

Generated by PasDoc 0.17.0.snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.