History

7.0 Insertions

7.1 Overview

Insertions are artifacts in a web.alive map that display content that is not part of the map. There are 3 kinds: Image Insertions, Document Insertions, and Movie Insertions. Simply put, if a web.alive map constructs a "room", then insertions can be used to display things on the walls.

Insertions have several advantages over placing content directly into a map:
  • Insertions handle the download and display of their own content. It is not part of the main level download to the client. As a result, a map is "usable" by a client before any of the insertions start their downloads. This means that a map is visible to a user faster and the user can interact with the map while the insertion come to the client.
  • Insertion formats are smaller than their associated Unreal forms and thus are quicker to download.
  • Because Insertion content is not part of the level content, they can be changed without restarting the web.alive server and this change can be executed by the end user. The primary mechanism for doing this is called Upload. Image Insertions also support direct setting of their URLs.
Currently the insertion formats are as follows:
  • Image insertions support JPG, PNG and GIF.
  • Document insertions support PDF, PPT, PPTX, and JPG. JPG is considered to be a single page document. Content developers that wish to use Powerpoint to make document insertions must have Powerpoint installed on their computers.
  • Movie insertions support BINK (.bik). NOTE: Movie insertions are deprecated as of release 3.0

7.2 Insertion Construction

Content developers should know that an insertion consists of two objects - an actor and a programmic texture. The pair work together to provide the insertion functionality.

The programmic texture is responsible for the following:
  • Content download.
  • Content conversion to forms digestible to Unreal.
  • Display.
The actor is responsible for the following:
  • Control functions (e.g. Play, Stop, Next Page, Previous Page, Reload, Upload, etc.)
  • State synchronization between client and server. It is through this mechanism that the actor coordinates state between multiple clients. For example, the document insertion actor uses state synchronization to ensure that all clients are looking at the same page of a document.
  • Positional services. This means that any function that requires a position in the 3D space must be performed by the actor as textures do not have positions. Currently only the Movie actor has a positional service - the position of the Movie actor is the source of the movie audio.

The insertion actor holds a reference to the insertion texture (This is set in web.alive editor using the properties DocumentTexture, ImageTexture, or MovieTexture). Basically the actor holds a reference to the programmic texture and "drives it". Every insertion texture must have an associated insertion actor.

7.3 Insertion Objects

The insertion objects are as follows:
  • MovieTexture (in Engine)
  • MovieActor (in Engine)
  • DocumentTexture (in Chainsaw)
  • DocumentActor (in Chainsaw)
  • ImageTexture (in Chainsaw)
  • ImageActor(in Chainsaw)

As an implementation note, ImageTexture and DocumentTexture share software. This artifact can be seen in the web.alive editor by the property section “InsertionTexture”. InsertionTexture can also be seen in the texture creation list. The content developer can ignore this implementation artifact.

Even among insertions, the movie insertion is special. Its location in the Engine package is needed because:
  • special code had to be placed in the 3D renderer to make it work. This caused a dependency that forced it lower in the system.
  • the movie insertion needed access to the Unreal audio system.

In the web.alive editor, all these objects are easy to find. The only exception would be MovieActor which is a subclass of Keypoint.

7.3.1 Deprecated Insertion Properties

Insertions have existed for many releases of web.alive and have changed significantly. New features, improvements, and simplifications for the content developer have caused some properties to be deprecated. This means the software no longer uses them and the content developer need not set them anymore. The follow are the currently deprecated properties:

ImageTexture
  • DownloadingTexture
  • ShowDownloadingTextureInEditor
  • ConvertingTexture
  • ShowConvertingTextureInEditor
  • ErrorTexture
  • ShowErrorTextureInEditor
  • RelativeOrAbsoluteURL (Relative URLs are deprecated. Absolute are not. See below)
DocumentTexture
  • DownloadingTexture
  • ShowDownloadingTextureInEditor
  • ConvertingTexture
  • ShowConvertingTextureInEditor
  • ErrorTexture
  • ShowErrorTextureInEditor
  • PageNotFoundTexture
  • DefaultDocumentPageCount
  • RelativeOrAbsoluteURL (Relative URLs are deprecated. Absolute are not. See below)
MovieTexture
  • RelativeOrAbsoluteURL (Relative URLs are deprecated. Absolute are not. See below)

7.4 A Quick Example

Setting up an insertion is easy (a lot easier than it used to be ). Before we get into all the properties and options that are available, here is a quick step-by-step example of setting up an image insertion.

Other insertions are similar:
  • In the web.alive editor, open an existing project or create a new one – let’s call it Example.
  • Copy your media file, let’s call it example.jpg, into directory <workspace>/Projects/Example/Images.
  • In the Texture Browser, use New… to create an ImageTexture. Give it a name and package as you would when creating a regular texture.
  • Set the Filename property (in group InsertionTexture) to “example.jpg”. You should now see your image in the editor. It’s now a texture.
  • Set ResizeWidth and ResizeHeight to the sizes you want your image resized within. These do not have to be a power of 2.
  • Place the insertion into your world like you would any texture.
  • Using the Actor Browser, create an ImageActor and place it near the ImageTexture.
  • In the ImageActor, set the ImageTexture property to the new ImageTexture you’ve just created.

That’s it. The insertion is set up. You will likely follow these steps with triggers to stimulate the ImageActor and further Actor configuration.

7.5 Insertions and their Content

All the insertions look for content files using the same method. There are 2 properties used to control this called Filename and AbsoluteOrRelativeURL.

The first place an insertion will look for a content file is on the local file system. This only happens for insertions used within the web.alive editor or when web.alive is launch in its standalone form from the web.alive editor. When used with a server, insertions do not seach for media on the local file system.

Local file access uses the Filename property only and looks for files under the web.alive editor workspace as outlined below:
  • ImageTexture will look for media in <workspace>/Projects/<ProjectName>/Images/<Filename>
  • DocumentTexture will look for media in <workspace>/Projects/<ProjectName>/Documents/<Filename>
  • MovieTexture will look for media in <workspace>/Projects/<ProjectName>/Movies/<Filename>

By default your workspace is located in <My Documents>/web.aliveEditor. The value of the Filename property must match the name of the file the insertion should display in the associated directory.

If the content file cannot be found locally or local access is not being used (such as with a server), then the insertion texture turns to the web to try and get the file.

In the most common case, nothing further needs to be set to allow this to work. When a project is exported from the web.alive editor using a WAE file and then deployed to a server, the deployment will ensure that the insertion file is placed correctly for web distribution and ensure that the server/client will construct URLs correctly. If the insertion worked in the editor using local access, it should work correctly in a web.alive client using network access when deployed with WAE. Content developers should never be affected by default URL construction (so it is not covered here).

The default URL construction can be overridden by using the AbsoluteOrRelativeURL property. The name is a bit misleading as part of its functionality was deprecated. Relative URLs are not used anymore. If the value starts with http or https, then the URL is considered to be absolute and the resulting URL is simply a concatenation of the two properties.

For example:

If the AbsoluteOrRelativeURL value does not start with http or https, then the URL is considered to be relative and is ignored. Default URL construction is used instead.

Use of AbsoluteOrRelativeURL is now exceedingly rare and only really concievable with image insertions. Content developers should leave it empty as we expect to fully deprecate it in the future. For image insertions, it is better to set a default image and then allow the user to set the image url from the client directly(see below).

Finally, in the web.alive editor or standalone, default URLs are constructed using "http://127.0.0.1" for the rare case were local access fails. The implication is that to test URL download in standalone for insertions, you must run a web server on your machine. This is also rare and errors from the editor that complain about “Unable to download from http://127.0.0.1” usually mean the Filename property is not set correctly or the media file is not in the correct directory.

7.5.1 Content for Document Insertions – JPG Pages

Document insertions have a more complex file structure than outlined above. In addition to the document file that is in a Documents directory or on the web, the content must also include a sibling directory containing JPG pages. One page of the document is represented by one JPG image. The structure can be seen in the follow:

Documents
 - Doc1.pdf
 - Doc1
   - Slide1.jpg
   - Slide2.jpg
   ...
   - Slide30.jpg

 - Doc2.ppt
 - Doc2
   - Slide1.jpg
   - Slide2.jpg
   ...
   - Slide82.jpg

 - Doc3.jpg
 - Doc3
   - Slide1.jpg

The document insertion uses the JPG pages to display pages of the document. It’s basically a JPG viewer. The content developer might wonder if the original document file is needed at all. The answer is that it does. The original file performs the following key functions:

  • It allows the web.alive Editor to generation the JPG pages automatically.
  • The document insertion uses the presence or absence of the original file locally (as described above) to determine if the JPG pages should be accessed locally or retrieved from the web. As a result, the document insertion will not mix some pages locally and others from the web.
  • The Upload function (described in a subsequent section), uses the original document file as a security template to determine if a client has permission to upload JPG pages to the server.

There are a number of ways of generating the JPG pages:

  • When the main web.alive editor starts, it will generate JPG pages for all files in the Documents directories of its current project. JPG pages will be generated if they don’t exist or if the document file is newer than Slide1.jpg.
  • If you add a document while the web.alive editor is running and then point a document insertion at it, the editor will generate the JPG pages for it.
  • You can manually create JPG pages from a PDF file using the following command:
    <web.alive install>\System\pdf2jpg.exe <filename>
  • You can manually create JPG pages from a PPT file using the following command:
    <web.alive install>\System\CZ-Ppt2Jpg.exe <filename> /h
  • Manually creating a JPG page from a JPG “document” is left as an exercise for the reader

7.6 Insertion Sizing

Sizing is important in this system. For ImageTexture and DocumentTexture, source media is resized to a texture size that is controlled by the properties ResizeWidth and ResizeHeight as shown in Figure 47. The resize preserves aspect ratio using letterboxing. ResizeWidth and ResizeHeight do not have to be a power of 2 but the resulting texture has to be. As a result, the texture dimensions are the next power of 2 up from the resize width and height. The resulting resized image is centered on the texture. If powers of 2 are not used, a framing effect is created.

For MovieTexture, the movie media must be a power of 2 natively (MovieTexture will not scale movie frames like the other two scale images and pages). MovieTexture does not support a resize ability because it would be too expensive to resize every frame. In addition, movie insertions have state textures which are displayed when the movie is in certain states (downloading, stopped, error, etc). These state textures must also be the same size as the media.

7.7 Alpha Control

Alpha channel or transparency can be controlled for image and document insertions. There is no alpha support for movies. The following are the rules:

  • DO NOT use bAlphaTexture on image or document textures like a static texture. It will have no affect as the code running the insertion texture sets this flag explicitly in software.
  • The framing area or letterboxing around an image or page can be either black or transparent. This is controlled by the property bAlphaInsertion. If false, the border is black. If true, the border is transparent.
  • For image insertions that use a PNG image for content, there is the possibility that the PNG image will have an alpha channel. To activate this channel and see the transparency, you also use bAlphaInsertion=true.

7.8 Activation, Delayed Loading, and Volume Interactions

The point in time when an insertion starts to download its file and load is called activation. Activation of insertions does not happen as soon as the level starts. It’s actually delayed slightly until all the state data is present on the client. This is roughly when you see your avatar in the level.

The content developer can delay activation for an insertion by using the ActivationVolumeTag property that is on every insertion texture and effectively links the insertion to one or more physics volumes. By setting this property, the insertion will not activate until the ActivationVolumeTag matches the Tag of the PhysicsVolume where the player pawn is standing. In this manner, an insertion can be delayed until the player pawn walks into a room (for example).

By matching to the Tag of Physics Volumes, multiple volumes can be used to activate an insertion if required.
But please note:
  • Only PhysicsVolume (or a subclass) can be used for this purpose. We recommend ChainsawVolume.
  • It must be possible for an avatar to put the insertion into its field of view from the volume or the insertion will not activate from that volume. This is an Unreal restriction – even if the insertion is activated, it will not start because Unreal does not consider it “relevant”.

Insertions that are delayed in this fashion do not download the insertion file to their cache. Please note that this is not a security feature as the insertion file can only be truly secured at the web server. But this does prevent insertion files that are not relevant to a user from ending up in their cache. This feature is best used for closed rooms where the insertion content should only be available to the people in the room. The feature can also be used to improve the scalability of a level when large/many insertion files are being used.

By default, the ActivationVolumeTag property for new insertions is set the empty string which indicates that the insertion loads as soon as it can. If this property is set but does not match the tag of any line-of-site physics volumes, then the insertion will never load. Content developers should note that this property is completely ignored inside the web.alive editor where the relationship of player pawn to physics volume is not maintained.

7.9 Insertion Textures and the web.alive editor

  • Working with insertion textures in the web.alive editor can take some special knowledge. These textures are dynamic and change through time which can cause strange behavior in the editor.
  • First of all, the editor doesn't update consistently. You sometimes need to toggle a properly in the texture editor to see the display update. This is especially true of MovieTexture.
  • Second, some properties cannot be changed while the texture is downloading or converting in the editor. When this happens, the propery is set back to what it was. Due to poor refresh characteristics in the editor, you may need to close and open the texture browser when this happens.

7.10 Triggers, Events, and the Insertion Actors

As stated previously, the insertion actors control functions. What functions an insertion actor supports can be seen in their properties. In the Events category you will see properties like NextPageTriggerAction. There is one of these trigger action properties per function that the actor supports and the values of these properties are used to control events.

As with other aspects of Unreal, a trigger defines an Event property and that event is delivered to all actors whose Tag property matches this string. But once the event is delivered to the actor, the actor doesn't know which of its functions to invoke as a result of the event. This is where trigger actions come in. If the TriggerAction property of the Trigger matches one of the trigger actions in the actor, that function is invoked.

Now normally a content developer doesn't have to worry about matching trigger action strings. All the actors have defaults. In addition there is a trigger subclass for every function under UseTrigger and LookAndUseTrigger which define the associated default for the trigger action in the trigger. The content developer only needs to worry about matching trigger action strings if a new trigger is being used to invoke the function.

We expect content developers to use LookAndUse triggers mostly as these can be used to create remote controls using the trigger's various collision schemes (which is outside the scope of this document). The LookAndUseTrigger has a variety of properties and options but the three that will be the most important to those working with insertions will be Event, TriggerAction, Range, and PermittedGroups. Event and TriggerAction have been discussed. Range defines how close the user has to be to the trigger to activate it. PremittedGroups define the security groups that are permitted to activate the trigger (an empty list allows all to activate). For example, using Range and PermittedGroups, you can make a trigger only active to authenticated users within 5 “meters”.

Document insertions have the following special trigger types associated with them:
  • FirstPageLookAndUseTrigger
  • NextPageLookAndUseTrigger – we consider this the default action.
  • PreviousPageLookAndUseTrigger
  • ReloadLookAndUseTrigger
  • UploadLookAndUseTrigger
  • UploadImageFromClipboardLookAndUseTrigger
  • ResetToDefaultLookAndUseTrigger
  • DocumentMenuLookAndUseTrigger – supports all actions above (see Menu Triggers below)
  • RepetitiveTimerTrigger – See Auto-advance section.
Movie insertions have the following special trigger types associated with them:
  • DecreaseMovieVolumeTrigger
  • IncreaseMovieVolumeTrigger
  • PauseMovieLookAndUseTrigger
  • PlayMovieLookAndUseTrigger
  • StopMovieLookAndUseTrigger
  • TogglePlayPauseMovieLookAndUseTrigger – we consider this the default action.
  • ReloadLookAndUseTrigger
  • UploadLookAndUseTrigger
  • ResetToDefaultLookAndUseTrigger
  • MovieMenuLookAndUseTrigger – supports all actions (see Menu Triggers below)
Image insertions have the following special trigger types associated with them:
  • LaunchURLLookAndUseTrigger - we consider this the default action.
  • ReloadLookAndUseTrigger
  • UploadLookAndUseTrigger
  • UploadImageFromClipboardLookAndUseTrigger
  • SetLaunchURLLookAndUseTrigger
  • SetImageURLLookAndUseTrigger
  • ResetToDefaultLookAndUseTrigger
  • ImageMenuLookAndUseTrigger – supports all actions (see Menu Triggers below)

As you can imagine, these lists can fall out of date quickly as functions are added to the actors. The best authority is to look at the actor properties in the web.alive editor. Most of the triggers above also have UseTrigger varieties but they are rarely used.

7.10.1 The Special Trigger – MenuLookAndUseTrigger

Each insertion had a special trigger which is used to support popup menus associated with the insertion. These triggers are DocumentMenuLookAndUseTrigger, MovieMenuLookAndUseTrigger, and ImageMenuLookAndUseTrigger. Collectively called the MenuLookAndUseTriggers, they have the following functions:
  • On left-click, the trigger operates as a normal LookAndUse trigger. This provides a default action for the menu if desired.
  • On right-click, the trigger raises an object menu containing all the operations supported on the insertion. The user can select an operation and invoke it as if they had explicitly left-clicked on the appropriate trigger.
  • If a file(s), is dropped on the trigger, it will send the file drop to the target actor for processing. See the next section for a discussion on Upload and Drag’n’Drop.

The content developer should consider using these triggers as they have a number of advantages:

  • If space or time is at a premium and a console/remote control cannot be built, then the entire insertion can be operated from a single trigger. Note that we don’t recommend using object menus without some affordance but in some cases the minimum support is useful.1
  • As new operations are added to the insertion, they will be added to the menu via software. As a result, new operations can be added without modifying level contents every time.
  • When building a console/remote control, the content developer has the luxury of adding only the most commonly used functions knowing that the rest are available in the menu.
  • By placing these triggers in front of insertions, the content developer gives the insertion-texture object semantics (it can be dropped on, it can be clicked on, there is a menu). More on this in the next section.
The default left-click behaviour of these triggers is matched to the expected default insertion action. These are:
  • Next Page for documents
  • Toggle Play/Pause for movies
  • Launch URL for images

As usual, these are controlled by TriggerAction in the trigger and can be changed if desired.

As for the menu, the trigger actions for all menu items are available for modification in the editor. They exist in their own section (for ImageMenuLookAndUseTrigger the section is ImageMenuTriggerActions) and have defaults that match the associated insertion actor. If you change a trigger action in the insertion actor, you must make the same change in the menu trigger. In addition, you can clear a trigger action (web.alive Editor sets it to “None”) in the menu trigger and that will remove the menu item from the menu for that trigger. For example, this is useful if you don’t want an insertion menu to support Upload.

These menu triggers respect Range and Permitted Groups as you would expect. If the user is out of range, the default menu comes up and not the insertion menu. Permission to the menu actions is slightly more complicated that the basic LookAndUseTrigger. The actions in the menu are divided into two groups – the regular actions and the admin actions. The regular actions are controlled by PermittedGroups as before. The admin actions are controlled by a new list call PermittedGroupsForAdminActions. If PermittedGroupsForAdminActions is empty, then PermittedGroups is used for the admin actions. In this case, the entire menu is access controlled as a unit.

The admin actions are as follows:
  • Document Insertion – Upload (both trigger and drag’n’drop), Upload from Clipboard, Reload, and Delete Uploaded File (Reset To Default).
  • Movie Insertion – Upload (both trigger and drag’n’drop), Reload, and Delete Uploaded File (Reset To Default).
  • Image Insertion - Upload (both trigger and drag’n’drop), Upload from Clipboard, Reload, Set Image URL, Set Launch URL, and Reset To Default.

7.11 Upload

Upload is a new feature for insertions where a user can interact with an insertion in the virtual world and cause a file(s) on their local disk to be uploaded to the web server and then used by that insertion for content. It avoids the content file provider from having to know where the web server is, how to get access to the web server, and what file to replace.

7.11.1 Upload Interactions

There are two ways that the user interacts with the Upload feature. Upload can be invoked via either Trigger or Drag'n'Drop. Using the first interaction, the following happens:

1) The user triggers the upload.
2) The user is presented with a file selection dialog.
3) The user selects a file.
4) The upload proceeds using that file.

Using the second interaction, the following happens:

1) The user drags the file onto an upload drop target (an upload capable actor or trigger).
2) The upload proceeds using that file.

7.11.2 Trigger Interaction

Upload triggering is done with the new UploadLookAndUseTrigger. There is also a proximity version but we don't expect anyone to use it. Every insertion that is expected to support upload should have a visible upload trigger to give the user clear affordance of the ability. Its defined just like all the other triggers - Reload, NextPage, etc. Upload triggering can also be done from the MenuLookAndUseTriggers.

Drag'n'Drop Interaction

The insertion actors act as file drop targets. In addition, some triggers will proxy a file drop to their targeted actors, thus becoming drop targets themselves. The following support file drop:

Document Insertion Drop Targets:
      - DocumentActor (not recommended – no permitted groups control)
      - UploadLookAndUseTrigger
      - NextPageLookAndUseTrigger
      - DocumentMenuLookAndUseTrigger
Image Insertion Drop Targets:
      - ImageActor (not recommended – no permitted groups control)
      - UploadLookAndUseTrigger
      - ImageMenuLookAndUseTrigger
      - LaunchURLLookAndUseTrigger
Movie Insertion Drop Targets:
      - MovieActor (not recommended – no permitted groups control)
      - UploadLookAndUseTrigger
      - MovieMenuLookAndUseTrigger

The physical 3-d drop target is defined by the actor/trigger's collision zone.

Simulating Insertion "Replacement"

It’s natural for the user to drag a file and drop it right onto the insertion texture to indicate "replace this". Unfortunately, the insertion texture is inert in unreal so the content developer has to do some extra work to make this function. The idea here is to place an invisible actor or trigger in front of the insertion texture with a large collision zone to "catch" the drop and handle it as if the user had dropped directly on the texture. It is already a common practice to put invisible NextPage triggers in front of DocumentTextures to give the same kind of effect.

We recommend using LookAndUseTriggers for this and not actors. The LookAndUseTrigger supports access control (i.e. PermittedGroups) which can be used to limit who can drop files. The same kind of access control is not supported in the insertion actors themselves. Soooo:

For simulated replacement in front of DocumentTextures – use DocumentMenuLookAndUseTrigger. If a menu is not desired use NextPageLookAndUseTrigger (be aware that Upload and NextPage actions cannot be access controlled separately with NextPageLookAndUseTrigger).

For simulated replacement in front of ImageTextures – use ImageMenuLookAndUseTrigger . If a menu is not desired use LaunchURLLookAndUseTrigger (be aware that Upload and Launch URL actions cannot be access controlled separately with LaunchURLLookAndUseTrigger).

For simulated replacement in front of MovieTextures – use MovieMenuLookAndUseTrigger . If a menu is not desired use TogglePlayPauseMovieLookAndUseTrigger (be aware that Upload and Toggle Play Pause actions cannot be access controlled separately with TogglePlayPauseMovieLookAndUseTrigger ).

7.11.3 Reset To Default – Triggers and Concepts

Every insertion supports the ResetToDefault trigger action which is primarily used to delete uploaded files. The name “Reset To Default” can be confusing since it is often labelled differently on Menu Triggers. The user will see “Delete Uploaded File…” instead for document and movie insertions because these insertions only support upload as a mechanism for user customization. But we expect that user customizations to expand beyond upload in the future so the trigger and trigger action are called “Reset To Default”. The following shows the variations:

  • Reset to Default for document insertions will remove the uploaded file(s) if it exists and reset the insertion back to its original document. On the menu trigger its called “Delete Uploaded File…”.
  • Reset to Default for movie insertions will remove the uploaded file if it exists and reset the insertion back to its original movie. On the menu trigger its called “Delete Uploaded File…”.
  • Reset to Default for image insertions will do the following:
    - Remove the uploaded image if it exists and reset the insertion back to its original image.
    - Reset the Image URL back to the default if it’s been set explicitly.
    - Reset the Launch URL back to the default if it’s been set explicity. The default may be no URL.

On the menu trigger its called “Reset To Default…”.

7.11.4 Restrictions and Limitations

Upload is not supported in StandAlone mode - only client-server. This means that the content developer cannot test Upload within the web.alive editor or in the standalone test mode from the editor. The only partial exception is that the Upload Trigger can be tested to see if it is hooked up correctly - it will raise the file selection dialog in standalone mode (if correctly targeted to an actor) but selecting a file will "beep" and reject the drop.

7.12 Insertions and UCC

This section is now obsolete but maintained for historical reference. All media are converted to texture in-process using threads. This section will be removed when we find a better place to put this valuable information.

ImageTexture and DocumentTexture convert the download format to texture files. Experience has shown that texture files are the fastest media for Unreal to digest and they can be cached for future use. This is what is happening during the converting state. Those working with insertions should know that PDF conversions are done using UCC commands that are run in their own process. The command is as follows: 

ucc pkg insert texture &lt;pathAndPackageName&gt; &lt;file&gt; &lt;options&gt;
   ucc pkg insert texture ../Cache/MyTexPkg ../Documents/MyDoc.pdf DXT=1 WIDTHHINT=512 HEIGHTHINT=512

Where <pathAndPackageName> is the package name you want with a path but without the .utx suffix. Where <file> is the JPG or PDF file.

JPG insertions are converted into texture packages using worker threads launched inside the client. They could also have used UCC but were changed to threads for performance.

7.13 Special features for the Image Insertion

Image insertions have several features that the other two do not have. These were added primarily to support advertising in the 3D environments.

First, the URL that the insertion uses to get its image can be set explicitly by the user. This is an alternative to Upload – instead of uploading a file, the insertion can be modified directly to point somewhere else on the web. The SetImageURLLookAndUseTrigger can be used to allow the user to set this URL via a dialog.

Second, image insertions can be used to launch URLs. The URL can be set by the content developer, by the user or both. When set by the content developer, the properties LaunchURL and LaunchURLTarget need to be set on the ImageActor (section Image). When set, these become the “default” launch URL. The user can override the launch URL using the SetLaunchURLLookAndUseTrigger which raises a dialog for that purpose. Finally the URL can be actually invoked using the LaunchURLLookAndUseTrigger (among other techniques).

7.14 Special features of the Document Insertion

The document insertion allows you to display pages offset from the current page. Imagine 3 displays on a podium where the presenter can see the current slide, the previous slide, and the next slide. This is controlled by the DocumentTexture property called PageOffset.

As mentioned before, the document insertion is based on JPG pages. This has a number of advantages including speed of download, speed of upload, better user experience, and better scalability.

7.14.1 Auto-advance for Document Insertions

Document Insertions support the ability to automatically page through their content in a continuous loop with a constant delay between each page change. This was added to support changing advertisments in the environment. To configure auto-advance, the content developer must add the RepetitiveTimerTrigger.

RepetitiveTimerTrigger is a trigger which fires itself on a regular timer interval. Keep the following in mind when it is being setup:
- Place it in the level near the DocumentActor.
- Configure it like a normal trigger, targeting the desired DocumentActor.
- There is no user interaction with this Trigger, so configure it as such – no visibility, no collision, etc.
- Set how often to advance the document with RepeatPeriodInSeconds (In the Events section).