Relief – Aspire Only

Reliefs are two dimensional grids of pixels with a height value associated at each pixel. They are used to represent 2D height fields that can have transparent regions. Reliefs can be created programmatically and converted into Components by adding a relief to the ComponentManager or obtained by querying a Component for its relief. The position of a relief is set using the Transform method on the associated component once it is created.

Constructor

Relief(integer pixel_width, integer pixel_height, double real_width, double_real_height) pixel_width (integer) The width of the relief in pixels pixel_height (integer)The height of the relief in pixels real_width(double) The width of the relief in real world units real_height(double) The height of the relief in real world units

Relief(Box2D bounds, float pixel_size)

bounds (Box2D) The real world dimensions of the relief pixel_size (float) The side length of a pixel in real world units

Properties

.Error

Interaction: Read Only

Returns: (bool) true if there was an error during relief construction

.PixelWidth

Interaction: Read Only

Returns: (integer) the width in pixels of the relief

.PixelHeight

Interaction: Read Only

Returns: (integer) the height in pixels of the relief

.RealWidth

Interaction: Read Only

Returns: (float) the real width of the relief

.RealHeight

Interaction: Read Only

Returns: (float) the real height of the relief

.XPixelSize

Interaction: Read Only

Returns: (integer) the width of a pixel in real units

.XPixelSize

Interaction: Read Only

Returns: (integer) the height of a pixel in real units

.Thickness

Interaction: Read Only

Returns: (float) the thickness of the block in real units (0.0 for reliefs created by Lua)

.SurfaceZ

Interaction: Read Only

Returns: (float) the surface z in real units (0.0 for reliefs created by Lua)

.Volume

Interaction: Read Only

Returns: (float) the volume of the relief

.IsTransparent

Interaction: Read Only

Returns: (bool) true if the relief consists entirely of transparent pixels

Methods

:Reset(float value, bool free_memory)

Sets all heights in the relief value(float) The height to set all pixels in the relief free_memory(bool) Has no effect, ignored

:MakeValuesTransparent(float value)

Makes all parts of the relief at the given height transparent value (float) The height of the pixels to be made transparent

:ReplaceTransparentValues(float value)

Replaces all transparent pixels with the given height value (float) The height that all transparent pixels will become

:PointIsOnModel(integer x, integer y)

Returns: (bool) true if x is between zero and the pixel width and y is between zero and the pixel height x (integer)The x coordinate of the pixel to test y (integer) The y coordinate of the pixel to test

:Set(integer x, integer y, float value)

Sets the height for the relief at the point to the specified value

x (integer)The x coordinate of the pixel to set y (integer) The y coordinate of the pixel to set value (float) The height value to assign to the pixel

:SetLowest(integer x, integer y, float value)

Sets the height for the relief at the point to whichever is lower, the current value or the passed value.

Returns: (bool) true if the height was changed
x (integer) The x coordinate of the pixel to set y (integer) The y coordinate of the pixel to set value (float) The height value to try and assign to the pixel

:Get(integer x, integer y)

Returns: the height for the relief at the point in pixel coordinates
x (integer)The x coordinate of the pixel to get y (integer) The y coordinate of the pixel to get

:GetInterpolated(double x, double y)

Returns: the interpolated height for the relief for the specified coordinate
x(double) The x coordinate in pixel units y(double) The y coordinate in pixel units

:GetMinMaxZ()

Returns: the maximum and minimum z values of the relief taking into account the thickness and a boolean flag indicating if the model is transparent
local transparent, min_z, max_z = relief:GetMinMaxZ()

:GetTrueMinMaxZ()

Returns: the maximum and minimum z values of the relief ignoring the thickness and a boolean flag indicating if the model is transparent
local transparent, min_z, max_z = relief:GetTrueMinMaxZ()

:Add(float value)

Adds onto all non transparent pixels vaIue (float) The height to add onto each non transparent pixel

:Subtract(float value)

Subtracts from all non transparent pixels vaIue (float) The height to subtract from each non transparent pixel

:Multiply(float value)

Multiply all non transparent pixels vaIue (float) The height to multiply each non transparent pixel

:MergeHeighest(float value, bool is_abs_value, bool preserve_transparent)

Merge heighest over the entire relief value (float) The height value to merge into the relief is_abs_value(bool) If true the reliefs Z offset is taken into account preserve_transparent(bool) If true transparent pixels remain transparent

:MergeLowest(float value, bool is_abs_value, bool preserve_transparent)

Merge lowest of the entire relief value (float) The height value to merge into the relief is_abs_value(bool) If true the reliefs Z offset is taken into account preserve_transparent(bool) If true transparent pixels remain transparent

:CombineReliefs(Relief relief, CombineMode combine_mode)

Combines the relief relief (Relief) The relief to combine into this combine_mode (CombineMode) How the relief should be combined:BlendBetweenReliefs(Relief first_relief, Relief second_relief, double blend_factor)

Returns: a new relief that is a blended version of the two passed reliefs
first_relief (Relief) The first relief to blend
second_relief (Relief) The second relief to blend, must have the same dimensions as the first blend_factor(double) 0.0 all first, 1.0 all second

:FlipY()

Flips the relief mirroring it vertically

:FlipX()

Flips the relief mirroring it horizontally

:TransposeXY()

Transposes the reliefs pixels

:RotateClockwise90()

Rotates the relief 90 degrees clockwise

:RotateCounterClockwise90()

Rotates the relief 90 degrees counter clockwise

:RenderTriangle(Point3D p1, Point3D p2, Point3D p3, bool merge_high)

Renders a triangle into the relief p1(Point3D)The first point of the triangle p2(Point3D)The second point of the triangle p3(Point3D)The third point of the triangle merge_high(bool) If true merge the triangle high

:CreateSlice(float min_z, float max_z, bool make_below_min_z_transparent)

Returns: a relief sliced between the specified Z range min_z (float) The minimum Z value to include max_z (float) The maximum Z value to include make_below_min_z_transparent (bool) If true heights below min_z become transparent

:ColumnIsTransparent(integer x, float transparent_value)

Returns: (bool) true if the column consists entirely of pixels that are of the transparent value x (integer) The column pixel coordinate transparent_value (float) The Z value to consider transparent

:RowIsTransparent(integer y, float transparent_value)

Returns: (bool) true if the row consists entirely of pixels that are of the transparent value x (integer) The row pixel coordinate transparent_value (float) The Z value to consider transparent

:CreateSectionCopy(integer min_x, integer min_y, integer max_x, integer max_y)

Returns: a subset of the relief between the coordinate ranges min_x (integer) The minimum x pixel coordinate to include min_y (integer) The minimum y pixel coordinate to include max_x (integer) The maximum x pixel coordinate to include max_y (integer) The maximum y pixel coordinate to include

:TiltRelief(Point2D anchor_pt, Point2D direction_pt, double angle)

Tilts the relief anchor_pt(Point2D)Start of vector determining tilt direction direction_pt(Point2D)End of vector determining tilt direction angle(double) The the angle to tilt in degrees

References

Please Note: The base material for the contents found in this WiKi was sourced from Vectric Lua Interface for Gadgets, version 2.05, published September 12, 2018. by Vectric Ltd. Most current document from Vertric can be downloaded at Vertric Developer Information