Unit CastleUtils

Current platform of the compiled application.

Note that you can also use compilations symbols: CASTLE_IOS, CASTLE_NINTENDO_SWITCH. And of course all the symbols defined by Pascal compilers: (for OS:) ANDROID, MSWINDOWS, UNIX, LINUX etc., (for CPU:) CPUX86_64, CPUI386, CPUAARCH64 etc.

This item has no description.

Convert string to a platform name. Case (the difference between upper and lower letters) is ignored. Raises Exception on invalid platform name.

Check condition.

Exceptions raised

ECheckFailed

Raised with ErrMessage if condition TrueValue if false.

Search the array for a given value. Returns index (zero-based) or -1 if not found.

Useful for writing case as:

case ArrayPosStr(variable, [val1, val2]) of
  0 : Something1;
  1 : Something2;
  else SomethingElse;
end;

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Name and version of the Pascal compiler used to compile this unit.

See also

TCastleApplicationProperties.Description

Print some common information about application, for example to use in –help command-line output.

SPlatformDescription

Describe current platform, OS, CPU.

Describe current platform, OS, CPU. This is all detected looking at compilation symbols defined when compiling this unit.

See also

TCastleApplicationProperties.Description

Print some common information about application, for example to use in –help command-line output.

SCompilerDescription

Name and version of the Pascal compiler used to compile this unit.

Warning: this symbol is deprecated: use ApplicationProperties.Description

This item has no description.

If not TrueValue then RaiseLastOSError.

This item has no description.

Like standard Format, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

In general this ignores locale, so also ThousandSeparator doesn't matter (conversion is done like it is #0).

Like standard FloatToStr, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

In general this ignores locale, so also ThousandSeparator doesn't matter (conversion is done like it is #0).

Like standard FloatToStr, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

In general this ignores locale, so also ThousandSeparator doesn't matter (conversion is done like it is #0).

Display float as nice concise number to read (but not necessarily with absolute precision). This means:

(

Like the ...Dot routines, this always uses dot (.) as a decimal separator, regardless of the user's locale settings.

Like standard TryStrToFloat, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

Also it doesn't Trim the argument (so whitespace around number is not tolerated), and in general ignores locale (standard StrToFloat looks at ThousandSeparator).

This item has no description.

Like standard StrToFloat, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

Also it doesn't Trim the argument (so whitespace around number is not tolerated), and in general ignores locale (standard StrToFloat looks at ThousandSeparator).

Like standard StrToFloatDef, but always uses dot (.) as a decimal separator for the floating point numbers, regardless of the user's locale settings.

Also it doesn't Trim the argument (so whitespace around number is not tolerated), and in general ignores locale (standard StrToFloat looks at ThousandSeparator).

Current application mode, see TCastleApplicationMode for various possible values.

Are we in design-time now. Shortcut for CastleApplicationMode <> appRunning.

Nice exception description. Contains the ClassName (unless it descends from EShortErrorMessage), and the exception Message (if it descends from Exception).

Warning: this symbol is deprecated: Use Halt

This item has no description.

Return the symlink target path. Like Libc.ReadLink or FpReadLink, but more comfortable, it returns a normal Pascal string.

Exceptions raised

EOSError

In case of any failure (non-existing FileName etc.)

Swap variables values.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Make sure the Smaller value is <= than the Larger value, by eventually swapping them.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Assign the smaller value from X, Y to Smaller variable, the other one to Larger variable.

This item has no description.

This item has no description.

This item has no description.

Update value of A to be a minimum of A, B. Works like A := Min(A, B), but is marginally faster, since you don't have to do anything when A is already smaller.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Update value of A to be a maximum of A, B. Works like A := Max(A, B), but is marginally faster, since you don't have to do anything when A is already larger.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Index (0, 1 or 2) of maximum / minimum of 3 numbers.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Warning: this symbol is deprecated: Use ClampVar

This item has no description.

Warning: this symbol is deprecated: Use ClampVar

This item has no description.

Warning: this symbol is deprecated: Use ClampVar

This item has no description.

Warning: this symbol is deprecated: Use ClampVar

This item has no description.

Warning: this symbol is deprecated: Use ClampVar

This item has no description.

Remaining 3D coordinates (0, 1 or 2) except the given coordinate, in the ascending order.

E.g. Coord = 0, then it sets First = 1 and Second = 2.

The coordinates are in ascending order, so e.g. for Coord = 1 we return First = 0, Second = 2.

Remaining 3D coordinates (0, 1 or 2) except the given coordinate, in order to cycle.

E.g. Coord = 0, then it sets First = 1 and Second = 2.

The coordinates are in order to cycle, so First = (Coord + 1) mod 3, Second = (Coord + 2) mod 3. E.g. for Coord = 1 we return First = 2, Second = 0.

Increase Value by Change, nicely wrapping in [0..MaxValue], accepting also negative Change. The final value is always in the [0..MaxValue] range, even when initial Value was outside.

Linear interpolation between two values. Returns (1-A)*L + A*H.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Linear interpolation between 2 angle values, in radians. Goes from one value to the other through a shortest path. Values are interpreted "modulo 2 * Pi", i.e. there's no difference between Angle1 = 0.1, Angle1 = 2 * Pi + 0.1, Angle1 = -2 * Pi + 0.1 etc.

Smallest multiple of Multiplicator that is still >= Value.

Largest power of 2 still <= Value. When Value = 0 returns 0.

Exponent of the largest power of 2 that it's still <= Value. Like BiggestPowerOf2, except that this returns which power of 2 it is, while BiggestPowerOf2 just returns exactly this power. Biggest2Exponent(0) = -1.

Smallest exponent such that 2ˆthis exponent is >= Value. Smallest2Exponent(0) = -1 (this is different situation than Smallest2Exponent(1), when we return 0.

Smallest power of 2 that is >= Value. Like Smallest2Exponent, except here we return 2ˆSmallest2Exponent(Value). Returns 0 when Value = 0.

Check is Value an exact power of 2.

This item has no description.

This item has no description.

Linearly map value from a one range to another.

Consider how SourceVal is placed in the [SourceBegin .. SourceEnd] (it may be outside of this range, it all still works OK). It has some distance to range start (SourceBegin), and some distance to range end (SourceEnd).

We want to find another number, that is identically placed in another range [DestBegin .. DestEnd].

1. Such that Distance(SourceVal, SourceBegin) / Distance(SourceVal, SourceEnd) = Distance(Result, DestBegin) / Distance(Result, DestEnd).

2. And such that it's on the same side of the range. So if SourceVal is beyond SourceEnd (that is, SourceBegin < SourceEnd < SourceVal or SourceBegin > SourceEnd > SourceVal) then the result must be similarly beyond DestEnd.

   As you can see, this works regardless if one, or both, of the ranges increase (range end is larger than range begin).

MapRangeClamped additionally at the end clamps the result to be within [DestBegin, DestEnd] range (or [DestEnd, DestBegin] range, in case DestEnd < DestBegin).

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Random Float value in the given range, result is between RangeBegin and RangeEnd. Always pass arguments such that RangeBegin < RangeEnd.

This item has no description.

Random integer value in the given range, result is always >= RangeBegin and < RangeEnd. So result is never equal to RangeEnd, this is often convenient, and makes RandomIntRange(0, N) consistent with Random(N). Always pass arguments such that RangeBegin < RangeEnd.

This item has no description.

Random int value in the given range, result is always >= RangeBegin and <= RangeEnd. Always pass arguments such that RangeBegin <= RangeEnd.

This item has no description.

This item has no description.

Random -1 or +1.

Angle between a 2D line segments and OX axis. Angle 0 means that Y1 = Y2 and X2 > X1, then the angle increases as you rotate CCW. In radians.

Calculate power Base to Exponent, knowing both arguments (and so, also the result) are >= 0.

This item has no description.

Trivial factorial with Int64 result. Beware, the results very quickly stop to fit inside Int64 range.

Better DivMod version, in case Dividend may be < 0.

This fixes lack of DivMod with negative Remainder (for FPC at least older than 2.2.4, see fpc-devel thread "Math.DivMod results should be signed" on 2006-03-21, http://www.mail-archive.com/[email protected]/msg04565.html).

And workarounds faulty DivMod behavior with FPC 2.4.0, see http://bugs.freepascal.org/view.php?id=15453

Like DivMod (return result of Integer division and a remainder), but always return Remainder >= 0.

This is useful in case when Dividend < 0. Standard DivMod (and Pascal div and mod operators) return then Result rounded toward zero, and Remainder may be < 0. This procedure will return Result rounded toward negative infinity, and Remainder will always be >= 0.

Returns Ceil(A / B), but calculated faster and more precisely (without floating-point help).

This item has no description.

Calculate Integer division and modulo on two Float arguments. Requires that A >= 0 and B > 0, and the Result is always >= 0.

Tries to secure against floating point imprecision. It's always guaranteed that Remainder >= 0 and <= B (and usually should be < B, but this cannot be guaranteed).

Calculate Float modulo of division on two Float arguments. Works for any A (lesser than zero too). Assumes that B > 0.

Tries to secure against floating point imprecision. It's always guaranteed that Remainder >= 0 and <= B (and usually should be < B, but this cannot be guaranteed).

This item has no description.

This item has no description.

Our version of CoTan, to workaround old FPC bug.

Floor from Sqrt(Value).

Hermite interpolation between two values. For X changing from Edge0 to Edge1, the resulting value changes from 0 to 1, smoothly (not with a linear speed). This is useful to make nicer transition from one value to another, it often looks better than using directly Lerp or MapRange.

Just like GLSL smoothstep: http://www.khronos.org/opengles/sdk/docs/manglsl/xhtml/smoothstep.xml

Utility functions to control the endianess. Note: Floating-point versions support Single and Double, but not Extended (which means different things on different platforms/compilers, see https://castle-engine.io/coding_conventions#no_extended , and in practice binary files don't contain numbers >= Double).

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Convert degrees to radians, consistent with CastleScript deg() function and display of rotations in CGE editor. In CGE, all functions take rotations in radians.

Remove from the FileName the last extension (including the dot). Note that if the FileName had a couple of extensions (e.g. blah.x3d.gz) this will remove only the last one. Will remove nothing if filename has no extension.

It is not adviced to use this function, better to operate on URLs and MIME types instead of filenames and extensions, see CastleUriUtils.

Extracts two last extensions from the filename, if it has two extensions. If the filename has only one extension, returns that one extension, if the filename has no extension — returns empty string, similar to ExtractFileExt.

This is useful to detect file types from filenames like model.x3d.gz, where ExtractFileExt returns only .gz. This function will return .x3d.gz.

It is not adviced to use this function, better to operate on URLs and MIME types instead of filenames and extensions, see CastleUriUtils.

Warning: this symbol is deprecated.

Extracts from FileName the name of file, without directory, without last extension and without any Windows drive letter.

Deprecated, since we use URLs everywhere and also because this has very low usage. Use DeleteURIExt(ExtractURIName(URL)) if you really need to.

Warning: this symbol is deprecated.

Returns FileName with directory (path) part replaced with given NewPath. NewPath must contain trailing PathDelim.

Deprecated, since we use URLs everywhere and also because this has very low usage.

Include / exclude the last path delimiter, if necessary. These are just comfortable shorter names for IncludeTrailingPathDelimiter and ExcludeTrailingPathDelimiter.

For Delphi, we also fix treatment of slash on Windows: it should be treated as a path delimiter, as Windows accepts both slashes and backslashes.

This item has no description.

Check is the given Path absolute.

Path may point to directory or normal file, it doesn't matter. Also it doesn't matter whether Path ends with PathDelim or not.

Note for Windows: while it's obvious that 'c:\autoexec.bat' is an absolute path, and 'autoexec.bat' is not, there's a question whether path like '\autoexec.bat' is absolute? It doesn't specify drive letter, but it does specify full directory hierarchy on some drive. This function treats this as not absolute, on the reasoning that "not all information is contained in Path".

See also

IsPathAbsoluteOnDrive

Just like IsPathAbsolute, but on Windows accepts also paths that specify full directory tree without drive letter.

Just like IsPathAbsolute, but on Windows accepts also paths that specify full directory tree without drive letter.

See also

IsPathAbsolute

Check is the given Path absolute.

Checks is the directory name special, like "." or "..".

The precise definition of "special" is that you cannot ever create or even have any filenames / directories named like this.

Add Suffix to the filename, right before extension. Returns DeleteFileExt(FileName) + Suffix + ExtractFileExt(FileName).

Pointer arithmetic. Will wrap over if you add too much. Add may be negative. This is just a shortcut for PtrInt(Result) := PtrInt(P)+Add, without any range / overflow checks.

This item has no description.

Safer version of FreeMem, checks is parameter Nil, and sets it to Nil afterwards.

Check is memory filled with the given character. Returns -1 is True, or the number (between 0 .. Size - 1) or the first character different than AChar.

Check is memory filled with the given character. Returns simple boolean, use CheckIsMemCharFilled to get more informative result.

Check is memory filled with the Word (2 byte sequence). Size if the number of words (not bytes), this is consequent with Size parameter from FillWord from FPC's RTL.

Check is memory filled with the DWord (4 byte sequence). Size if the number of dwords (not bytes), this is consequent with Size parameter from FillDWord from FPC's RTL.

Calculate shift between A and B addresses (in bytes). Useful to pass as offsets to methods like TGLSLAttribute.EnableArray that wrap OpenGL vertex-array API. This is simply Result := A - B, except we do some typecasting.

This item has no description.

Warning: this symbol is deprecated: use SameMethods

Compare two methods.

This item has no description.

Write using a dialog box or console.

If we are a Windows GUI program (not IsConsole) then we use native Windows dialog boxes. Otherwise (a console is available, which is always true on non-Windows) we output the message using simple Writeln (to standard output for InfoWrite, or ErrOutput for ErrorWrite and WarningWrite).

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Warning: this symbol is deprecated.

Output messages, using console or dialog box.

If we're not on Windows or IsConsole, then we simply output Messages using Writeln.

If we're on Windows and not IsConsole, then every Messages is displayed in a separate dialog box. Dialog box uses our InfoBox routine, with Messages[I] being message content and title being Format(TitleFormat, [I + 1, Messages.Count]).

This is good for outputting a lot of information.

Deprecated. This just looks ugly in GUI version. It's better to present long information using only a console (just use Writeln), or only a full-featured GUI (like Lazarus LCL or our CastleUIControls).

Floating-point type with best precision.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Pointer to a boolean. Defined as ˆByte in some Delphi Windows unit, for FPC 1.0.x PBoolean is not available at all.

Infinite array of bytes.

This item has no description.

Pointer to TObject. Don't call this PObject or PTObject to avoid possible name clashes with other units (pointers are often used in situations that prevent good type-checking, so better to avoid name clashes to avoid some nasty errors).

Size (signed) used for various list types Count, Capacity, index variables.

Delphi uses Integer for this. FPC uses SizeInt for this (which may have larger size than Integer, FPC docs say it is matching pointer size, so 64-bit on 64-bit platforms).

Possible platforms supported by CGE. See Platform.

Values

• cpDesktop
• cpAndroid
• cpIOS
• cpNintendoSwitch

This item has no description.

Simple notify event with no Sender

Application mode.

Values

• appRunning: Application is running. We are not inside any editor (CGE editor, LCL/Delphi designer).
• appDesign: We are designing the application in CGE editor (or LCL/Delphi designer). Simulation is not started.
• appSimulation: We are designing the application and simulation has been started by user. The main feature of simulation right now is to test the physics at design-time. More features may be unlocked in particular components.
• appSimulationPaused: We are designing the application and simulation has been started and paused by the user.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Warning: this symbol is deprecated: use EShortErrorMessage

This item has no description.

Index of axis in 3D.

This item has no description.

New line sequence, suitable for current OS. Short name for LineEnding.

Castle Game Engine version.

Number of digits after the decimal point we show using FloatToStrDisplay by default. This affects the display of floats and vectors in CGE editor's object inspector.

This item has no description.

This item has no description.

This item has no description.

Pi / 2.

Pi * 2.

Root dir name. Empty if not applicable to this OS.

This item has no description.