Astrolabe/Minimap Icon Positioning System

From Esamynn's Wiki

Astrolabe » Astrolabe/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 on, 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.

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 (such as being inside an instance), or when in a Battleground.