scalability guidelines

Warning:
This tutorial covers only Mobile Widgets versions.
For a Tiny Mobile Widgets, use scalability guidelines for Tiny Mobile Widgets.

Working on mobile phones leads to work on different screen sizes. It would be heavy and restrictive to develop one application per screen resolution. So we have introduced the scalability feature. Developers write the application code once and for all. Helped by using a Message node all VRML scenes can be aware of the size of the screen and calculate size and positions of graphical elements. And even better: it is a "screen size changed" Message. So that VRML scenes are aware of the screen size and also WHEN screen size changed (dynamic). This last ability is useful on mobile phones that can switch from portrait to landscape mode.

Avoid calculations

Keep in mind this project targets low-end devices. Please limit size and position calculations to the bare essentials. You can add filter TRUE to each ImageTexture node which is bad rendered. But use it sparingly because it generates a lots of calculations in memory.

Default values

Our reference size is 240*320 (in pixels). it is important to avoid useless calculations on most of devices, that's why default sizes and translations are set for the 240*320 size. Calculations should be done only to manage other screen size.

Size informations

The screen size can be accessed by the Browser JavaScript API, method Browser.getWidth() and Browser.getHeight().

Size Changed event

The system can notify each VRML scene that the size changed (switch from portrait to landscape mode for example). Therefore, the VRML scene has to contain the following Message Node:

DEF SIZE_CHANGED Message {
    url "MEMOPLAYER"
}

This node listen to the "MEMOPLAYER" channel. You have to add a link message reception to a script function that does calculations. This link is done by the following ROUTE: (by convention, ROUTE are put at the end of the VRML scene)

ROUTE SIZE_CHANGED.data_changed TO SCRIPT.sizeHandler

Now, just add a new entry to the script in your VRML scene:

 function sizeHandler () {
   if (sizeHandler[0] == 'SIZE_CHANGED') { //check if notification is "SIZE_CHANGED". In fact channel "MEMOPLAYER" is also used for other type of notification
     updateScreenSize ();
    }
 }
 function updateScreenSize() {
  //some size calculations
 }

Aspect ratio for images

To avoid ugly stretches on images, don't forget to respect their aspect ratio. The image ratio is: imageWidth / imageHeight and vice versa. When you do scalability, you should calculate imageWidth or imageHeight and found the other helped by the ratio. It will keep the real aspect of the image. If it is bad rendered, you can use attribute filter TRUE inside the ImageTexture node. But filter uses a lot of CPU.

To support landscape and portrait mode, sometimes you will have to use the minimum between screen width and height to be sure that the scalable area fit with the real screen size.

Size notifier prototype

The SizeNotifier prototype manages the screen size events. It uses the sizeHandler mechanism describes upper to get screen size value. The SizeNotifier prototype is used in many SDK prototypes. This is the SizeNotifier prototype interface:

PROTO SizeNotifier [
  eventOut SFVec2f screenSize
  eventOut SFVec2f textScale
]

screenSize and textScale events (eventOut) propagate the values. In many cases, screenSize value is used in the script to compute sizes and positions of scene items. Style is also useful to defines values and ratios.
A good way to propagate the screen size is to defines each scene of a widget as a prototype. This tip eases the screenSize and the textScale use: it could be propagated with "IS" for script and for other protos.

See SizeNotifier prototype documentation for more informations about this prototype.

Aspect ratio

function screenSize() {
  var minScreenSize = screenSize.x ;
  if(screenSize.x > screenSize.y) minScreenSize = screenSize.y;

  // Scale bg to screen size
  bgRec.size.x = screenSize.x;
  bgRec.size.y = screenSize.y;

  // Scale logo to screen size (respect aspect ratio)
  logoRec.size.x = screenSize.x;
  logoRec.size.y = screenSize.x;
}

Size notifier

#MyScene.wrl

EXTERNPROTO SizeNotifier [] "SizeNotifier.wrl"

PROTO MyScene [
  # These nodes are defined here for to transmit their values with IS in MyScene
  field SFVec2f screenSize 0 0
  field SFVec2f textScale 0 0
] {

  # The SizeNotifier provides screenSize and textScale values
  SizeNotifier {
    screenSize IS screenSize
    textScale IS textScale
  }

  # screenSize is transmit to the background prototype
  Backgnd { screenSize IS screenSize }

  # screenSize and textScale use in the script
  Script {
    field SFVec2f screenSize IS screenSize
    field SFVec2f textScale IS textScale
    url "javascript:
      function screenSize() {
        Browser.print('The current screen size is ' + screenSize.x + 'x' + screenSize.y);
        Browser.print('The current text scale is ' + textScale.x + 'x' + textScale.y);
      }
    "
  }
}
MyScene {} # when the file is loaded MyScene.wrl , MyScene proto is loaded

The MyScene file could be loaded like this, from the main.wrl for example:

Inline { url [ "MyScene.m4m" ] }