eg-overlay-3d

eg-overlay-3d#

local overlay3d = require 'eg-overlay-3d'

The eg-overlay-3d module contains functions and classes that can be used to draw in the 3D scene, below the overlay UI.

Important

Objects here can be created during startup, update, or other events, but drawing can only occur during draw-3d.

Most of the rendering details are abstracted away so all that is needed is an image to use for a texture, and coordinates for display, either in the 3D scene (the ‘world’) or on the map or minimap.

Note

This module will render objects anytime their draw method is run during an draw-3d event, regardless of the UI state or MumbleLink data.

Module authors should track these states and only draw when appropriate.

Textures#

Textures are managed by the texture map class. A map can hold multiple textures that can be shared by multiple classes that use them. Module authors are encouraged to create a single map use it for all 3D rendering with the module.

Dimensions#

This module does not enforce any restrictions on texture dimensions when loading the data, however internally all textures are stored in square textures with dimensions that are a power of 2.

This should not affect sprites because the original dimensions of the image are stored and used when rendering them, but trails may not be rendered as expected if a non-square and/or non-power of 2 image is used.

3D Object Types#

Sprites or icons can be drawn using a o3dspritelist. Trails, paths, or walls can be drawn using the o3dtraillist. Both use textures from a o3dtexturemap.

World vs Map#

Both sprites and trails can be drawn either in the 3D world or on the 2D (mini)map. This module will automatically handle projection and viewport settings for either.

The difference is specified when creating the list (see spritelist() and traillist()).

When a trail or sprite is created as a world object, its coordinates are assumed to be in GW2 map coordinates, with the X axis for west (negative) and east (positive), Y axis for altitude or down (negative) and up (positive), and Z axis for south (negative) and north (positive).

Important

GW2 map coordinates are in inches, while the GW2 MumbleLink data is returned in meters. The eg-overlay-3d module assumes GW2 map coordinates are in inches, consistent with the game.

When a trail or sprite is created as a map object, its coordinates are assumed to be in GW2 continent coordinates, with the X axis for west (negative) and east (positive), Y axis for south (negative) and north (positive), and Z set to 0. When specifying coordinates for map objects, it is possible to just specify X and Y.

Examples#

local o3d =require 'eg-overlay-3d'

local textures = o3d.texturemap()

local sprites = o3d.spritelist(textures)

-- load texture image data from somewhere
local texturedata = '...'

-- add a texture
textures:add('Texture Name', texturedata)

-- attributes for a sprite
local attrs = {
    x = 10.1, y = 20, z = -50, -- location
    color = 0xFF00FFFF,
    size = 120,
    tags = { -- arbitrary info
        id = '1234',
        group = 'foo'
    }
}

-- add the sprite
sprites:add('Texture Name', attrs)

-- update it later
sprites:update({ group = 'foo' }, { color = 0x00FFFFFF })

-- eventually draw, sometime during a draw-3d event
sprites:draw()

-- trails are similar

-- add some other texture for a trail
textures:add('Some other texture', trailtexturedata)

local trails = o3d.traillist(textures)

-- trails are a path drawn along points
local trailpoints = {
    {0, 0, 0},
    {10, 10, 10},
    {20, 20, 20}
}

local trailattrs = {
    points = trailpoints,
    color = 0xFFFFFFFF,
    size = 60,
    wall = false,
    tags = {
        id = '5678',
        group = 'bar'
    }
}

traillist:add('Some other texture', trailattrs)

-- draw it eventually
traillist:draw()

Functions#

eg-overlay-3d.mousepointsat(x, y, z, radius)#

Determine if the mouse pointer is positioned near the given position.

This is determined by calculating a ray pointing from the camera through the mouse pointer and calculating if that ray would intersect a sphere with the given radius around the position.

Coordinates and radius is in map units (inches).

Parameters:

x (number)
y (number)
z (number)
radius (number)

Return type:

boolean

Version History

Version	Notes
0.1.0	Added

eg-overlay-3d.mousepointermapcoords()#

Return the continent coordinates of the mouse pointer. If the mouse is not currently over the (mini)map nil is returned instead.

Return type:: number

Example#

local o3d = require 'eg-overlay-3d'

local cx,cy = o3d.mousepointermapcoords()

Version History

Version	Notes
0.1.0	Added

eg-overlay-3d.texturemap()#

Create a new o3dtexturemap object.

Return type:: o3dtexturemap

Version History

Version	Notes
0.1.0	Added

eg-overlay-3d.spritelist(texturemap[, position])#

Create a new o3dspritelist object.

Parameters:

texturemap (o3dtexturemap)
position (string) – (Optional) How the sprites in this list will be positioned. See below, default 'world'.

Return type:

o3dspritelist

Position Values

Value	Description
`'world'`	Sprites are drawn within the 3D world, coordinates must be in map coordinates.
`'map'`	Sprites are dawn on the (mini)map, coordinates must be in continent coordinates.

Version History

Version	Notes
0.1.0	Added

eg-overlay-3d.traillist(texturemap[, position])#

Create a new o3dtraillist object.

Parameters:

texturemap (texturemap)
position (string) – (Optional) How the trails in this list will be positioned. See below, default 'world'.

Return type:

o3dspritelist

Position Values

Value	Description
`'world'`	Trails are drawn within the 3D world, coordinates must be in map coordinates.
`'map'`	Trails are dawn on the (mini)map, coordinates must be in continent coordinates.

Version History

Version	Notes
0.1.0	Added

Classes#

class eg-overlay-3d.o3dtexturemap#

A texture map holds a list of textures that other objects in this module use when being displayed.

clear()#

Remove all textures from this map and reset it to an initial state.

Danger

If sprite lists or other objects are still referencing textures within this map after this method is called their draws will not function properly.

Version History

Version	Notes
0.1.0	Added

add(name, data, mipmaps)#

Add a texture.

Parameters:

name (string) – The name of the texture, this will be used to reference it later when adding data to sprite lists and other objects.
data (string) – The texture data.
mipmaps (boolean) – Generate mipmaps, default true.

Implementation Detail

EG-Overlay uses the Windows Imaging Component to load data, so any format it supports can be used.

All textures are loaded as 4 channel BGRA images.

Version History

Version	Notes
0.1.0	Added

has(name)#

Returns true if this map has a texture named name.

Parameters:: name (string)
Return type:: boolean

Version History

Version	Notes
0.1.0	Added

class eg-overlay-3d.o3dspritelist#

A sprite list efficiently draws multiple sprites or icons within the 3D scene, each with their own attributes and texture. Sprite lists use textures from a o3dtexturemap.

A sprite list stores all sprite information in one place and can render all sprites in a single call, making it much more efficient to draw larger numbers of sprites than drawing each one individually.

In addition to the attributes used to display them, each sprite can also have arbitrary data stored in ‘tags.’ This can be used to remove or update individual or groups of sprites later.

add(texture, attributes)#

Add a sprite to this list. attributes must a table with the following fields:

Field	Description
x	The sprite’s x coordinate, in map units, default `0.0`.
y	The sprite’s y coordinate, in map units, default `0.0`.
z	The sprite’s z coordinate, in map units, default `0.0`.
tags	A table of attributes that can be used with `update()` and `remove()`. Note: the table is referenced directly, not copied.
size	The sprite’s size, in map units, default `80`.
color	Tint color and opacity, see Colors, default `0xFFFFFFFF`.
billboard	A boolean indicating if the sprite should always face the camera, default `true`.
rotation	A sequence of 3 numbers indicating the rotation to be applied to the sprite along the X, Y, and Z axes, in that order. Only applicable if `billboard` is `false`.
fadenear	A number that indicates how far away from the player a sprite begins to fade to transparent.
fadefar	A number that indicates how far away from the player a sprite will become completely transparent.

Parameters:

texture (string) – The name of the texture, see o3dtexturemap.add().
attributes (table) – See above

Version History

Version	Notes
0.1.0	Added

update(tags, attributes)#

Update the sprites that have matching tags.

An empty tags table matches all sprites. A sprite must match all tag values given, if a sprite does not have a value for a tag it will not match.

Returns the number of sprites updated.

Parameters:

tags (table)
attributes (table)

Return type:

number

Version History

Version	Notes
0.1.0	Added

remove(tags)#

Remove sprites that have matching tags.

An empty tags table matches all sprites. A sprite must match all tag values given, if a sprite does not have a value for a tag it will not match.

Parameters:: tags (table)
Returns:: The number of sprites removed.
Return type:: number

Version History

Version	Notes
0.1.0	Added

draw()#

Draw all sprites in this list.

Parameters:: map (boolean) – If true draw sprites on the map or minimap. Otherwise draw sprites in the 3D world.

Important

This method can only be called during draw-3d. Attempts to call it at any other time will result in an error.

Version History

Version	Notes
0.1.0	Added

class eg-overlay-3d.o3dtraillist#

A trail list displays multiple paths as flat 2D textures drawn along specified points.

clear()#: Clear this trail list and set it back to an initial state.

Note

This will not clear the texture list that this trail list references.

Version History

Version	Notes
0.1.0	Added

addtrail(texturename, attributes)#

Create a new trail.

attributes must be a table with the following fields:

Field	Description
points	A sequence of sequences, trail points. ie. { {1,1,1}, {2,2,2} }
tags	A table of attributes that can be used other methods of this list to update or remove trails with matching tags. Note: the table is referenced directly, not copied.
fadenear	A number that indicates how far away from the player a trail begins to fade to transparent.
fadefar	A number that indicates how far away from the player a trail will become completely transparent.

Parameters:

texturename (string) – The name of a texture in the texture list this trail list references.
attributes (table) – See above.

Version History

Version	Notes
0.1.0	Added

remove(tags)#

Remove trails that have matching tags.

Parameters:: tags (table)
Returns:: The number of trails removed.
Return type:: number

Version History

Version	Notes
0.1.0	Added

draw()#

Draw all of the trails in this list.

Important

This method can only be called during draw-3d. Attempts to call it at any other time will result in an error.

Version History

Version	Notes
0.1.0	Added

update(tags, attributes)#

Update attributes of trails with matching tags.

Parameters:

tags (table)
attributes (table)

Returns:

The number of trails updated

Return type:

integer

Version History

Version	Notes
0.1.0	Added

eg-overlay-3d

Contents

eg-overlay-3d#

Textures#

Dimensions#

3D Object Types#

World vs Map#

Examples#

Functions#

Classes#