LuaDocs/SceneManager

From Data Realms Wiki

Contents 1 Has no parent class 2 Properties 2.1 Scene 2.2 SceneDim 2.3 SceneWidth 2.4 SceneHeight 2.5 SceneWrapsX 2.6 SceneWrapsY 2.7 LayerDrawMode 2.8 GlobalAcc 2.9 OzPerKg 2.10 KgPerOz 3 Functions 3.1 GetOffset 3.2 SetOffsetX 3.3 SetOffsetY 3.4 GetScreenOcclusion 3.5 SetScreenOcclusion 3.6 GetTerrain 3.7 GetTerrMatter 3.8 GetMOIDPixel 3.9 SetLayerDrawMode 3.10 SetScroll 3.11 SetScrollTarget 3.12 GetScrollTarget 3.13 TargetDistanceScalar 3.14 CheckOffset 3.15 LoadUnseenLayer 3.16 MakeAllUnseen 3.17 AnythingUnseen 3.18 GetUnseenResolution 3.19 IsUnseen 3.20 RevealUnseen 3.21 RevealUnseenBox 3.22 CastSeeRay 3.23 CastStrengthSumRay 3.24 CastStrengthRay 3.25 CastWeaknessRay 3.26 CastMORay 3.27 CastFindMORay 3.28 CastObstacleRay 3.29 GetLastRayHitPos 3.30 FindAltitude 3.31 MovePointToGround 3.32 IsWithinBounds 3.33 SnapPosition 3.34 ShortestDistance 3.35 RegisterPostEffect 3.36 AddSceneObject 3.37 ClearPostEffects

Has no parent class

Generic Class. The singleton manager of all terrain and backgrounds in the RTE.

Go back to Class Index

Properties

Scene

Read-only property. The currently loaded scene, if any.The scene, ownership IS NOT TRANSFERRED!

SceneDim

Read-only property. The total dimensions (width and height) of the scene, in pixels.A Vector describing the scene dimensions.

SceneWidth

Read-only property. The total width of the scene, in pixels.An int describing the scene width.

SceneHeight

Read-only property. The total height of the scene, in pixels.An int describing the scene width.

SceneWrapsX

Read-only property. Indicates whether the scene wraps its scrolling around the X axis.Whether the scene wraps around the X axis or not.

SceneWrapsY

Read-only property. Indicates whether the scene wraps its scrolling around the Y axis.Whether the scene wraps around the Y axis or not.

LayerDrawMode

The current drawing mode of the SceneMan.The current layer draw mode, see the LayerDrawMode enumeration for the different possible mode settings.

GlobalAcc

Read-only property. The global acceleration (in m/s^2) that is applied to all movable objects' velocities during every frame. Typically models gravity.A Vector describing the global acceleration.

OzPerKg

Read-only property. Gets how many Ounces there are in a metric KilogramA float describing the Oz/Kg ratio.

KgPerOz

Read-only property. Gets how many metric Kilograms there are in an Ounce.A float describing the Kg/Oz ratio.

Functions

GetOffset

Gets the offset (scroll position) of the terrain.

Arguments:

• None.

Return value:

A Vector describing the offset (scroll) of the terrain in pixels.

SetOffsetX

Sets the horizontal offset (scroll position) of the terrain.

Arguments:

• A long that specifies the new horizontal offset value.
• Which screen you want to set the offset of.

Return value:

None.

SetOffsetY

Sets the vertical offset (scroll position) of the terrain.

Arguments:

• A long that specifies the new vertical offset value.
• Which screen you want to set the offset of.

Return value:

None.

GetScreenOcclusion

Gets the amount that a specific screen is occluded by a GUI panel or something of the sort. This will affect how the scroll target translates into the offset of the screen, in order to keep the target centered on the screen.

Arguments:

• Which screen you want to get the occlusion value of.

Return value:

A Vector that indicates the amount of occlusion of the screen.

SetScreenOcclusion

Sets the amount that a specific screen is occluded by a GUI panel or something of the sort. This will affect how the scroll target translates into the offset of the screen, in order to keep the target centered on the screen.

Arguments:

• A Vector that specifies the amount of occlusion of the screen.
• Which screen you want to set the occlusion of.

Return value:

None.

GetTerrain

Gets the SLTerrain, or 0 if no scene is loaded.

Arguments:

• None.

Return value:

A pointer to the SLTerrain. Ownership is NOT transferred!

GetTerrMatter

Gets a specific pixel from the total material representation of this Scene. LockScene() must be called before using this method.

Arguments:

• The X and Y coordinates of screen material pixel to get.

Return value:

An unsigned char specifying the requested pixel's material index.

GetMOIDPixel

Gets a MOID from pixel coordinates in the Scene. LockScene() must be called before using this method.

Arguments:

• The X and Y coordinates of screen Scene pixel to get the MO from.

Return value:

The MOID currently at the specified pixel location.

SetLayerDrawMode

Sets the drawing mode of the SceneMan, to easily view what's going on in the different internal SceneLayer:s.

Arguments:

• The layer mode to draw in, see the LayerDrawMode enumeration for the different possible settings.

Return value:

None.

SetScroll

Sets the offset (scroll position) of the terrain to center on specific world coordinates. If the coordinate to center on is close to the terrain border edges, the view will not scroll outside the borders.

Arguments:

• A Vector that specifies the coordinates to center the terrain scroll on.
• Which screen you want to set the offset of.

Return value:

None.

SetScrollTarget

Interpolates a smooth scroll of the view from wherever it is now, towards centering on a new scroll target over time.

Arguments:

• The new target vector in *scene coordinates*.
• The normalized speed at screen the view scrolls. 0 being no movement, and 1.0 being instant movement to the target in one frame.
• Whether the target was wrapped around the scene this frame or not.
• Which screen you want to set the offset of.

Return value:

None.

GetScrollTarget

Gets the currently set scroll target, screen is where the center of the specific screen is trying to line up with.

Arguments:

• Which screen to get the target for.

Return value:

Current target vector in *scene coordinates*.

TargetDistanceScalar

Calculates a scalar of how distant a certain point in the world is from the currently closest scroll target of all active screens.

Arguments:

• Which world coordinate point to check distance to/from.

Return value:

A normalized scalar representing the distance between the closest scroll target of all active screens, to the passed in point. 0 means it's the point is within half a screen's width of the target, and 1.0 means it's on the clear opposite side of the scene.

CheckOffset

Makes sure the current offset won't create a view of outside the scene. If that is found to be the case, the offset is corrected so that the view rectangle is as close to the old offset as possible, but still entirely within the scene world.

Arguments:

• Which screen you want to set the offset of.

Return value:

None.

LoadUnseenLayer

Loads a bitmap from file and use it as the unseen layer for a team.

Arguments:

• The path to the bitmap to use as the unseen layer.
• Which team we're talking about.

Return value:

Whether the loading was successful or not.

MakeAllUnseen

Sets one team's view of the scene to be unseen, using a generated map of a specific resolution chunkiness.

Arguments:

• The dimensions of the pixels that should make up the unseen layer.
• The team we're talking about.

Return value:

None.

AnythingUnseen

Tells whether a team has anything still unseen on the scene.

Arguments:

• The team we're talking about.

Return value:

A bool indicating whether that team has anyhting yet unseen.

GetUnseenResolution

Shows what the resolution factor of the unseen map to the entire Scene is, in both axes.

Arguments:

• The team we're talking about.

Return value:

A vector witht he factors in each element representing the factors.

IsUnseen

Checks whether a pixel is in an unseen area on of a specific team.

Arguments:

• The X and Y coords of the scene pixel that is to be checked.
• The team we're talking about.

Return value:

A bool indicating whether that point is yet unseen.

RevealUnseen

Reveals a pixel on the unseen map for a specific team, if there is any.

Arguments:

• The X and Y coord of the scene pixel that is to be revealed.
• The team to reveal for.

Return value:

A bool indicating whether there was an unseen pixel revealed there.

RevealUnseenBox

Reveals a box on the unseen map for a specific team, if there is any.

Arguments:

• The X and Y coords of the upper left corner of the box to be revealed.
• The width and height of the box to be revealed, in scene units (pixels)
• The team to reveal for.

Return value:

None.

CastSeeRay

Traces along a vector and reveals pixels on the unseen layer of a team as long as the accumulated material strengths traced through the terrain don't exceed a specific value.

Arguments:

• The team to see for.
• The starting position.
• The vector to trace along.
• A Vector that will be set to the position of where the sight ray was terminated. If it reached the end, it will be set to the end of the ray.
• The material strength limit where
• For every pixel checked along the line, how many to skip between them for optimization reasons. 0 = every pixel is checked.

Return value:

Whether any unseen pixels were revealed as a result of this seeing.

CastStrengthSumRay

Traces along a vector and returns how the sum of all encountered pixels' material strength values. This will take wrapping into account.

Arguments:

• The starting position.
• The ending position.
• For every pixel checked along the line, how many to skip between them for optimization reasons. 0 = every pixel is checked.
• A material ID to ignore, IN ADDITION to Air.

Return value:

The sum of all encountered pixels' material strength vales. So if it was all Air, then 0 is returned (Air's strength value is 0).

CastStrengthRay

Traces along a vector and shows where along that ray there is an encounter with a pixel of a material with strength more than or equal to a specific value.

Arguments:

• The starting position.
• The vector to trace along.
• The strength value of screen any found to be equal or more than will terminate the ray.
• A reference to the vector screen will be filled out with the absolute location of the found terrain pixel of less than or equal to above strength.
• For every pixel checked along the line, how many to skip between them for optimization reasons. 0 = every pixel is checked.
• A material ID to ignore, IN ADDITION to Air.
• Whetehr the ray should wrap around the scene if it crosses a seam.

Return value:

Whether a material of equal or more strength was found along the ray. If not, the fourth parameter have been set to last position of the ray.

CastWeaknessRay

Traces along a vector and shows where along that ray there is an encounter with a pixel of a material with strength less than or equal to a specific value.

Arguments:

• The starting position.
• The vector to trace along.
• The strength value of screen any found to be equal or less than will terminate the ray.
• A reference to the vector screen will be filled out with the absolute location of the found terrain pixel of less than or equal to above strength.
• For every pixel checked along the line, how many to skip between them for optimization reasons. 0 = every pixel is checked.
• Whetehr the ray should wrap around the scene if it crosses a seam.

Return value:

Whether a material of equal or less strength was found along the ray. If not, the fourth parameter have been set to last position of the ray.

CastMORay

Traces along a vector and returns MOID of the first non-ignored non-NoMOID MO encountered. If a non-air terrain pixel is encountered first, g_NoMOID will be returned.

Arguments:

• The starting position.
• The vector to trace along.
• An MOID to ignore. Any child MO's of this MOID will also be ignored.
• To enable ignoring of all MOIDs associated with an object of a specific team which also has team ignoring enabled itself.
• A specific material ID to ignore hits with.
• Whether to ignore all terrain hits or not.
• For every pixel checked along the line, how many to skip between them for optimization reasons. 0 = every pixel is checked.

Return value:

The MOID of the hit non-ignored MO, or g_NoMOID if terrain or no MO was hit.

CastFindMORay

Traces along a vector and shows where a specific MOID has been found.

Arguments:

• The starting position.
• The vector to trace along.
• An MOID to find. Any child MO's of this MOID will also be found. ------------ ???
• A reference to the vector screen will be filled out with the absolute location of the found MO pixel of the above MOID.
• A specific material ID to ignore hits with.
• Whether to ignore all terrain hits or not.
• For every pixel checked along the line, how many to skip between them for optimization reasons. 0 = every pixel is checked.

Return value:

Whether the target MOID was found along the ray or not.

CastObstacleRay

Traces along a vector and returns the length of how far the trace went without hitting any non-ignored terrain material or MOID at all.

Arguments:

• The starting position.
• The vector to trace along.
• A reference to the vector screen will be filled out with the absolute location of the first obstacle, or the end of the ray if none was hit.
• A reference to the vector screen will be filled out with the absolute location of the last free position before hitting an obstacle, or the end of the ray if none was hit. This is only altered if thre are any free pixels encountered.
• An MOID to ignore. Any child MO's of this MOID will also be ignored.
• To enable ignoring of all MOIDs associated with an object of a specific team which also has team ignoring enabled itself.
• A specific material ID to ignore hits with.
• For every pixel checked along the line, how many to skip between them for optimization reasons. 0 = every pixel is checked.

Return value:

How far along, in pixel units, the ray the pixel of any obstacle was encountered. If no pixel of the right material was found, < 0 is returned. If an obstacle on the starting position was encountered, 0 is returned.

GetLastRayHitPos

Gets the abosulte pos of where the last cast ray hit somehting.

Arguments:

• None.

Return value:

A vector witht he absoltue pos of where the last ray cast hit somehting.

FindAltitude

Calculates the altitide of a certain point above the terrain, measured in pixels.

Arguments:

• The max altitude you care to check for. 0 Means check the whole scene's height.
• The accuracy within screen measurement is acceptable. Higher number here means less calculation.

Return value:

The altitude over the terrain, in pixels.

MovePointToGround

Takes an arbitrary point in the air and calculates it to be straight down at a certain maximum distance from the ground.

Arguments:

• The point to start from. Should be in the air, or the same point will be returned (null operation)
• The max altitude in px you want the point to be above the ground.
• The accuracy within screen measurement is acceptable. Higher number here means less calculation.

Return value:

The new point screen is no higher than accuracy + max altitude over the terrain.

IsWithinBounds

Returns whether the integer coordinates passed in are within the bounds of the current Scene, considering its wrapping.

Arguments:

• Int coordinates.
• A margin

Return value:

Whether within bounds or not, considering wrapping.

SnapPosition

Returns a position snapped to the current scene grid.

Arguments:

• The vector coordinates of the position to snap.
• Whether to actually snap or not. This is useful for cleaner toggle code.

Return value:

The new snapped position.

ShortestDistance

Calculates the shortest distance between two points in scene coordinates, taking into account all wrapping and out of bounds of the two points.

Arguments:

• The two Vector coordinates of the two positions to find the shortest distance between.
• Whether to check if the passed in points are outside the scene, and to wrap them if they are.

Return value:

The resulting vector screen shows the shortest distance, spanning over wrapping borders etc. Basically the ideal pos2 - pos1.

RegisterPostEffect

Registers a post effect to be added at the very last stage of 32bpp rendering by the FrameMan.

Arguments:

• The absolute scene coordinates of the center of the effect.
• A 32bpp BITMAP screen should be drawn centered on the above scene location in the final framebuffer. Ownership is NOT transferred!
• The intensity level this effect should have when blended in post.
• 0 - 255.

Return value:

None.

AddSceneObject

Takes any scene object and adds it to the scene in the appropriate way. If it's a TerrainObject, then it gets applied to the terrain, if it's an MO, it gets added to the correct type group in MovableMan.

Arguments:

• The SceneObject to add. Ownership IS transferred!

Return value:

Whether the SceneObject was successfully added or not. Either way, ownership was transferred. If no success, the object was deleted.

ClearPostEffects

Clears the list of registered post processing scene effects.

Arguments:

• None.

Return value:

None.

Go back to Class Index