Astrolabe

From Esamynn's Wiki
Jump to: navigation, search

Contents

Astrolabe is an embeddable library for placing icons on the Minimap, and on World Maps. Icons that are placed on the Minimap using Astrolabe are placed in a special buffer and their positions are continuously updated for player movement, based on the world map coordinates provided when the icon was initially placed. Icons remain in this buffer until they are removed.


General Notes

  • a coordinate data point consists of 4 numbers: continent, zone and xPos and yPos (with TOPLEFT being the 0,0 point and BOTTOMRIGHT being the 1,1 point)
  • continent 0 is the world of Azeroth, 1 is Kalimdor, 2 is Eastern Continent, 3 is Outland, 4 is Northrend, 5 is The Maelstrom, 6 is Pandaria
  • a zone of 0 or nil indicates that you want the continent itself (this value is generally, but not guaranteed to be, ignored when continent == 0)
  • a floor of 0 or nil indicates are equivalent in specifying that you want no floor, or the zone itself if the zone has Micro-Dungeon maps


Minimap Icon Positioning System

Astrolabe includes a system that AddOns can utilize to place icons on the Minimap frame, using World Map Coordinates, without having to worry about the details of translating the world map position information into the Minimap's frame of reference, or having to deal with the details of constantly updating the position of such icons as the player moves around in the game world.


Basic Usage

Adding/Updating Icons

To get Astrolabe to start managing an icon, use the PlaceIconOnMinimap API function. You can pass this function any anchorable UI widget, and a valid World Map Point. This function adds the icon to the position management buffer. Icons in the management buffer are automatically anchored to the Minimap, and this anchor is updated regularly as the player moves through the game world. If the position specified when the icon was added to the buffer is off the edge of the Minimap, then the icon will be anchored along the edge of the Minimap.

To update the position that an icon is placed at, simply call PlaceIconOnMinimap again with the icon and a new position.


Removing Icons

To remove an icon from the position management buffer, just call RemoveIconFromMinimap with the icon that you wish to remove.

To clear all icons from the buffer, call RemoveAllMinimapIcons. CAUTION: this removes all icons managed by Astrolabe, not just yours.

Icons can also be automatically removed from the buffer for any of the following reasons:

  • PLAYER_LEAVING_WORLD fires
  • the location of the player changes such that there is no longer any meaningful way to relate the icon's specified position to the player's current position


Technical Details

Astrolabe manages the position of icons in its buffer by way of using pre-calculated data, and a series of calculations to translate world map coordinates into distances relative to the player's current position. Internally Astrolabe works in game yards. Minimap icon positions are updated every frame, but the number of icons actually updated each frame is varied depending on the client's current frame rate. The number of icons updated each frame is determined by the current frame rate multiplied by the MinimapUpdateMultiplier variable. For the regular, incremental update cycle, there is a hard cap on the number of icons updated each frame of 50. For the full recalculation update, the final number is also multiplied by 2.

Most updates will consist of a call to UpdateMinimapIconPositions, which performs only an incremental update on icons which are currently in the positioning buffer. The other update function, CalculateMinimapIconPositions, is called when certain events occur, and performs a complete re-calculation of all icon positions from their provided world map position. These events include the re-activation of the update cycle, PLAYER_ENTERING_WORLD or MINIMAP_UPDATE_ZOOM firing, and an upgrade of the library.

The update cycle itself is tied to the Visible state of a frame that is parented to the Minimap frame of the default UI. This means that whenever the Minimap is not visible then the Astrolabe update cycle is not running. The update cycle is restarted whenever this frame's OnShow handler fires. The update frame is hidden whenever there is no valid player position available.


World Map Monitor

Astrolabe has a system that monitors the visible status of known World Map frames, and avoids actively calling WoW client API functions that fire WORLD_MAP_UPDATE while any such frames are visible. This system utilizes a global table called "WorldMapDisplayFrames" to keep allow AddOns that create new world map frames to easily allow this system to learn about them. The WorldMapFrame in the default UI is, of course, monitored by this system by default.


Providing Compatibility

AddOns that create a new frame that is sensitive to the WORLD_MAP_UPDATE event, in such a way that its firing is disruptive to the AddOn's normal operation, can add this frame to the global table WorldMapDisplayFrames using table.insert(). This will cause Astrolabe to avoid causing WORLD_MAP_UPDATE to fire when it is attempting to update the positions of icons it is managing. This means that if the current map zoom does not show a valid position for the player, the update cycle will be halted until all monitored frames are hidden.


Public API

Astrolabe ยป API

General Utility Functions

ComputeDistance( m1, f1, x1, y1, m2, f2, x2, y2 ) - takes two sets of coordinates and computes the distances between them in game yards
GetCurrentPlayerPosition() - returns the player's current position on the world map
GetUnitPosition( unit, noMapChange ) - returns a world map position for the specified unit
GetMapID( continent, zone ) - returns the map ID that corresponds to the specified Zone Index
GetMapInfo( mapID, floor ) - returns information about a given map
GetNumFloors( mapID, floor ) - returns the number of floors a map has
TranslateWorldMapPosition( M, F, xPos, yPos, nM, nF ) - calculates world map coordinates for another zone

Minimap Icon Placement

GetDirectionToIcon( icon ) - returns the direction from the player to the icon
GetDistanceToIcon( icon ) - returns the distance to the icon as computed at the last buffer update
IsIconOnEdge( icon ) - returns true if the icon is currently placed along the edge of the Minimap
PlaceIconOnMinimap( icon, map ID, floor, xPos, yPos ) - places an icon on the Minimap and adds it to the positioning buffer
Register_OnEdgeChanged_Callback( func, ident ) - registers a function to be called whenever the set of icons placed along the edge of the Minimap changes
RemoveIconFromMinimap( icon ) - hides the icon and removes it from the positioning buffer
RemoveAllMinimapIcons() - hides and removes all icons from the positioning buffer

Debug Methods

These methods should generally not be used during the normal functioning of an AddOn. They are publically available for various reasons, including being useful for debugging purposes.

CalculateMinimapIconPositions( reset ) - performs a complete update of all icons in the positioning buffer
RemoveAllMinimapIcons() - hides and removes all icons from the positioning buffer
UpdateMinimapIconPositions() - performs an incremental update of all icons in the positioning buffer

World Map Icon Placement

PlaceIconOnWorldMap( worldMapFrame, icon, continent, zone, xPos, yPos ) - places an icon on the specified world map frame


Events

Astrolabe currently monitors the following client generated events and takes the specified actions for each one.

MINIMAP_UPDATE_ZOOM
PLAYER_LEAVING_WORLD
PLAYER_ENTERING_WORLD
ZONE_CHANGED_NEW_AREA

Handler Scripts

OnEvent( frame, event ) -
OnUpdate( frame, elapsed ) -
OnShow( frame ) -
AllWorldMapsHidden() -


Uses of Astrolabe

The following is a list of AddOns that use Astrolabe.

Source Code

Astrolabe's source code repository can be found here: http://svn.esamynn.org/astrolabe/

The trunk/ is generally stable, and fit for regular use. Development that may destabilize stuff is generally done in a branch.

I generally DO NOT recommend using Subversion externals to include Astrolabe's code in your own project. However, if you insist on doing so, please be sure to specify a specific revision in your externals property.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox