Aw hud create

Minimum requirements
Added in version 4.1
SDK	build 64

int aw_hud_create (void)

Description

Sends a single HUD element.

Callback

AW_CALLBACK_HUD_RESULT

Notes

Only world server administration instances or those owned by a caretaker (i.e. aw_bool (AW_WORLD_CARETAKER_CAPABILITY) returns 1) may use this method.

If a blocking call is placed using an instance that is not a caretaker, or with AW_HUD_ELEMENT_ID set to 0 (zero), then it will block for some time and return RC_TIMEOUT.

Arguments

None

Argument attributes

There are many attributes you must set prior to calling aw_hud_create.

AW_HUD_ELEMENT_TYPE

Currently there are two supported types:

AW_HUD_TYPE_TEXT

AW_HUD_TYPE_IMAGE

Text elements display the contents of AW_HUD_ELEMENT_TEXT as text. This text is displayed in the viewport of a browser. It is scaled and centered within the extents of the element, utilizing the same mechanism as is used by the browser for sign objects.

Image elements treat AW_HUD_ELEMENT_TEXT as a texture name. This texture is downloaded and displayed in the viewport of a browser. It can either be tiled or scaled to fit the extents of the element. It is also possible to display a specified region of the texture.

AW_HUD_ELEMENT_TEXT

This provides the text or texture name for a HUD element.

It is possible to specify a mask texture by using a vertical bar. For example, "tree1.jpg|tree1m.bmp" would display the texture "tree1" using the mask "tree1m".

But, it is recommended to use PNG or GIF files when a mask is required.

AW_HUD_ELEMENT_ID

This is a unique identifier for the HUD element. It must be set to a positive integer.

If you create two elements with the same ID, the second will replace the first.

This ID is used in AW_EVENT_HUD_CLICK to identify which clickable (i.e. AW_HUD_ELEMENT_FLAGS had AW_HUD_ELEMENT_FLAG_CLICKS set) HUD element was clicked by a user.

AW_HUD_ELEMENT_SESSION

This specifies the session number of the user to recieve the HUD event. Using zero will cause the HUD element to be sent to all users.

AW_HUD_ELEMENT_ORIGIN

The nine anchor points that HUD elements may use

This specifies the "anchor point" for the HUD element. Note that viewports are re-sizeable on the client. At any time, the user may change the size and aspect ratio of their 3d window. This makes the predicable positioning of elements somewhat tricky. It would be unwise, for example, to place an element 300 pixels from the left edge of the screen and 400 pixels down from the top edge. For some users this would place the element near the middle. For others the element may wind up on the bottom edge. Some users with a very small viewport will not show the element at all!

So, to aid in the positioning of elements within an area of unpredicable size, elements have nine "anchor points" from which they may start. These are:

AW_HUD_ORIGIN_TOP_LEFT

AW_HUD_ORIGIN_TOP

AW_HUD_ORIGIN_TOP_RIGHT

AW_HUD_ORIGIN_LEFT

AW_HUD_ORIGIN_CENTER

AW_HUD_ORIGIN_RIGHT

AW_HUD_ORIGIN_BOTTOM_LEFT

AW_HUD_ORIGIN_BOTTOM

AW_HUD_ORIGIN_BOTTOM_RIGHT

The top, left, right and bottom points appear in the exact center of the given edge.

This point will specify the position of the upper left corner of your HUD element. Note that this means that for all origin points on the bottom and right edge of the screen, the element will not be visible in the default position! These origins are a place to start, but to properly place an element where you want it, you should set AW_HUD_ELEMENT_X and AW_HUD_ELEMENT_Y to an appropriate value.

For example, if you wanted to place a 64x64 element in the lower right corner, then you should set the origin to AW_HUD_ORIGIN_BOTTOM_RIGHT, and then set AW_HUD_ELEMENT_X and AW_HUD_ELEMENT_Y to -64.

AW_HUD_ELEMENT_OPACITY

The transparency of the HUD element. A value of 1.0 means it is totally opaque. A value of zero will make it invisible. Note that it will still react to mouse clicks, so you can use this to create invisible clickable regions within the 3d display.

AW_HUD_ELEMENT_X and AW_HUD_ELEMENT_Y

These two numbers specify the offset (in pixels) of the upper-left corner of the element from the given anchor point. Note that it is very easy to "lose" elements off the edge of the screen. If you specify AW_HUD_ORIGIN_TOP_RIGHT for the origin, then by default only the first row of pixels will be visible. Everything else will be off the right edge of the screen. To adjust for this, you can use the X and Y to offset the element from the origin. If your element is 200 pixels wide, then set the X position to -200 to have it appear properly in the upper-right corner.

AW_HUD_ELEMENT_Z

The Z order is used to determine the depth layer elements are drawn in. Elements are drawn in Z depth order, from low (closer or top layer) numbers to high numbers (further away or bottom layer). So if you want one element to appear on "top" of another, give it a lower z-order.

AW_HUD_ELEMENT_FLAGS

This field controls many things about the HUD element, such as texture mapping, render style, where the browser gets the texture, and many other aspects of element behavior. See AW_HUD_ELEMENT_FLAGS for more info on the available values.

AW_HUD_ELEMENT_COLOR

This attribute will set the text color for a text element. For an image element it will set the intensity of each color. For example, 0xFFFFFF (white) is maximum for all colors, which will make the image display normally, whereas 0x00FFFF (cyan) would filter out all the red.

AW_HUD_ELEMENT_SIZE_X and AW_HUD_ELEMENT_SIZE_Y

This is the size, in pixels, of the HUD element.

AW_HUD_ELEMENT_TEXTURE_OFFSET_X and AW_HUD_ELEMENT_TEXTURE_OFFSET_Y

This is the texture offset, in pixels. Note, these attributes do not apply to text elements.

If the stretch flag is not supplied, then textures are rendered with their upper-left corner set to the upper-left corner of the element, and then drawing the texture (repeating or trimming as needed) until the element is filled in.

If you have a 128x128 texture and you specify an X offset of 64, then it will begin drawing the texture so that the center of the texture is aligned with the left edge of the element.

Return values

RC_SUCCESS (1) (3)

RC_NOT_INITIALIZED (1)

RC_NO_INSTANCE (1)

RC_NO_CONNECTION (1)

The connection to the world is down.

RC_TIMEOUT (2)

There was no reply from the world.

RC_NO_SUCH_SESSION (3)

No avatar with a matching session number. Or a broadcast was not sent to anyone.

(1) Possible return values when a callback is installed.

(2) Only returned if a callback is not installed.

(3) Returned by the world server.

Returned attributes

AW_HUD_ELEMENT_SESSION

AW_HUD_ELEMENT_ID

Usage

void do_element (int session)
{
  /*
    This will send a HUD element to the given session number, which will 
    display the words "This is a HUD element" in yellow text in a 200 x 200
    square in the center of the viewport. If a user clicks within the square,
    then a AW_EVENT_HUD_CLICK will be sent to the bot.
  */
  int rc;
  
  aw_int_set (AW_HUD_ELEMENT_TYPE, AW_HUD_TYPE_TEXT);
  aw_string_set (AW_HUD_ELEMENT_TEXT, "This is a HUD element");
  aw_int_set (AW_HUD_ELEMENT_ID, 1);
  aw_int_set (AW_HUD_ELEMENT_SESSION, session);
  aw_int_set (AW_HUD_ELEMENT_ORIGIN, AW_HUD_ORIGIN_CENTER);
  aw_float_set (AW_HUD_ELEMENT_OPACITY, 1.0f);
  aw_int_set (AW_HUD_ELEMENT_X, -100);
  aw_int_set (AW_HUD_ELEMENT_Y, -100);
  aw_int_set (AW_HUD_ELEMENT_Z, 1);
  aw_int_set (AW_HUD_ELEMENT_FLAGS, AW_HUD_ELEMENT_FLAG_CLICKS);
  aw_int_set (AW_HUD_ELEMENT_COLOR, 0xFFFF00); /* RGB (255, 255,0) */
  aw_int_set (AW_HUD_ELEMENT_SIZE_X, 200);
  aw_int_set (AW_HUD_ELEMENT_SIZE_Y, 200);
  
  rc = aw_hud_create ();
  if (rc != RC_SUCCESS)
    printf ("Unable to create HUD element (reason %d)\n", rc);
}

See also

• HUD
• aw_hud_destroy
• AW_HUD_ELEMENT_FLAGS