Wikitude SDK API ReferencePositionable Class
A Positionable represents a virtual object that has Drawables
attached to it. The Positionable object is oblivious of any tracking
algorithms of the Wikitude SDK and has to be positioned manually from
within a plugin. It allows the rendering capabilities of the Wikitude
SDK to be extended by custom tracking algorithms.
A Positionable
- can be transformed by specifying transformation matrices or 2D screen positions from within a plugin.
- can have Drawables associated with it. These Drawables will represent the Positionable in the camera view.
- can have triggers associated with it. Triggers fire on certain events and execute functions to react on these actions.
- requires the field of vision related triggers to be called accordingly from with a plugin.
On creation, a unique character string identifier must be passed. The Positionable
may then be retrieved within the update method of a plugin from an input hash table
using the passed identifier. It may then be transformed by specifying the appropriate
transformation matrices or 2D screen positions. A Positionable can either be enabled
or disabled. If disabled, the attached Drawable will not be drawn.
On creation, setup parameters can be passed to customize the properties of
the Positionable.
// a circle used for representation
var circle = new AR.Circle(0.5);
// a Positionable having the circle attached as its drawable
var positionable = new AR.Positionable("myPositionable", {
drawables : {
cam : circle
}
});
For the render size of attached Drawables, see the chapter on SDUs.
Constructor
Item Index
Properties
Events
- onClick
- onEnterFieldOfVision
- onExitFieldOfVision
- triggers.onEnterFieldOfVision deprecated
- triggers.onExitFieldOfVision deprecated
Methods
destroy
()
Destroys the object.
drawables.addCamDrawable
-
drawable -
position
Adds Drawables to the ARObject in the camera.
Parameters:
-
drawableDrawable | Drawable[]The drawable(s) that should be added to the camera. Can either be a single Drawable, or an Array of Drawables.
-
positionNumber optionalThe position where the Drawable should be added in the array. If not specified, the Drawable will be added at the end of the array. Must be a whole number.
drawables.removeCamDrawable
-
drawable|position
Removes Drawables from the ARObject in the cam.
Parameters:
-
drawable|positionDrawable | [Drawable] | NumberWhen a single Drawable or an Array of Drawables is given, these Drawables will be removed from the array. When an integer is given, the Drawable at the specified position will be removed.
isVisible
()
Boolean
Returns the current visibility state of the ARObject. An ARObject is defined visible when at least one of the ARObject's locations (geolocations or visual tracker) is projected onto a screen coordinate which is currently visible on the screen.
Returns:
Whether the ARObject is currently visible on the screen (true) or invisble (false).
Properties
drawables.cam
Drawable[]
The Drawables which will be used to represent the ARObject
in the camera view.
Drawables in the array will
be printed starting with the Drawable at position 0, causing
Drawables at later indices to overlap the previously drawn
Drawables.
The array content should not be manipulated via the [] operator, as it cannot be guaranteed that the changes will be propagated through to the native application. The property should only be manipulated with arobject.drawables.addCamDrawable() and arobject.drawables.removeCamDrawable(), or directly set with arobject.drawables.cam = new Array(...);.
name
String
The unique identifier used to retrieve the Positionable in the update function of a custom plugin. The name needs to be unique. This property is read-only and can only be set on creation.
renderingOrder
Number
Drawables of different ARObjects might overlap. In this case, renderingOrder defines the rendering order of the Drawables of the ARObject.
ARObjects with higher renderingOrder values cause their Drawables to be drawn on top of the Drawables of ARObjects with lower renderingOrder values.
In case two ARObjects have set the same renderingOrder, the Drawables are rendered based on the distance, causing objects closer to the user to
overlap objects further away.
For example, If you want to bring Drawables of a certain ARObject to the very front, set the renderingOrder value of the corresponding ARObject
to a very high value.
For the printing order of Drawables within the same ARObject, refer to Drawable2D.zOrder.
Must be a whole number.
Default: 0
Events
onClick
Will be executed when any of the ARObject's Drawables have been clicked,
and none of the clicked Drawables's onClick() triggers (might also be referenced by another ARObject)
have been set to quit the click chain. ARObject.onClick() will be executed after any Drawable.onClick() triggers have
been executed.
In case multiple ARObjects are hit by the click, the order of the execution is defined by the distance
of the ARObject to the user, with the closest ARObject's click trigger executed first.
The return value of the function determines if, after the onClick()-Function was executed for this ARObject, the queue shall continue to execute onClick() for the next ARObject in the queue. In case the last ARObject in the queue still requests to continue the click-queue, context.onScreenClick() will be executed.
The return value of the function decides what to do next. If false, the click-queue should not stop with this ARObject. Thus, the next ARObject's onClick() function will be executed. This is the default value in case no return value is set or the function is not defined for this ARObject. If true, the queue-execution will stop at the current ARObject, underlying ARObjects will not receive onClick() calls.
onEnterFieldOfVision
The trigger will fire when the ARObject's visibility has
changed from invisible to visible.
The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onEnterFieldOfVision.
Event Payload:
-
targetNameStringIn case of a Trackable2DObject holds the name of the recognized target. Used in combination with wildcards for targetName.
onExitFieldOfVision
Will be executed when the ARObject's visibility has changed
from visible to invisible.
The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onExitFieldOfVision.
Event Payload:
-
targetNameStringIn case of a Trackable2dObject this will hold the name of the target that exited the field of vision.