Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

Porting your existing Three.js applications to BlackBerry 10

by BlackBerry Development Advisor on ‎05-07-2013 04:31 PM - edited on ‎05-07-2013 04:31 PM by BlackBerry Development Advisor (4,950 Views)

Background

So you’ve created a Three.js application; perhaps you’re already targeting mobile or perhaps you’ve only set your eye on the desktop. In either case, this porting guide aims to teach developers, currently leveraging Three.js, how they can go about bringing their HTML5 applications to the BlackBerry® 10 platform.

 

The BlackBerry platform has supported WebGL™ since the introduction of the BlackBerry® PlayBook™ OS 2.0, and the commitment to support and extend our browser’s WebGL capabilities has carried over to the BlackBerry 10 platform.

 

If you encounter any Three.js or WebGL related issues, the best way to have these addressed is to log a bug report in our Developer Issue Tracker, including:

  1. A “Hello World” sample that reproduces the issue.
  2. Device information (model, OS version, etc.)
  3. Any additional information on how to reproduce the issue (written steps, screenshots of errors, etc.)

Once filed, notify the author with a link to the Issue Tracker report so that it can be escalated to the development teams.

  1. Email: eoros@blackberry.com
  2. Twitter: @WaterlooErik
  3. Forums: oros

Device Resolutions

BlackBerry 10 launched with two flagship devices:

  • The BlackBerry® Z10; full-touch, 1280x768 resolution (15:9 aspect ratio); and
  • The BlackBerry® Q10; physical keyboard, 720x720 resolution (1:1 aspect ratio.)

Future devices have had their device resolutions standardized to minimize fragmentation for developers. BlackBerry 10 devices with physical keyboards will remain at the 720x720 device resolution while full-touch devices will possess a 1280x720 resolution; a standard 16:9 ratio.

 

For more information on this standardization, please refer to the following BlackBerry Developer Blog article. Additionally, best practices and recommendations for targeting BlackBerry 10 screens can be found here.

 

GPU Differences

The BlackBerry Z10 launched with two chipset variants:

  • Texas Instruments OMAP® 4470 1.5Ghz / Imagination GPU PowerVR SGX 544
  • Qualcomm® Snapdragon MSM8960 1.5Ghz / Qualcomm GPU Adreno 225

Performance-wise, both variants are comparable; however there is one primary difference that developers should be aware of, namely texture compression.

 

In many cases, especially larger mobile games, texture compression is important as it avoids having your application’s resources take up unnecessary space.

 

If you are looking to target both GPUs with a single BAR file, you will need to rely on uncompressed textures or 16-bit compressed textures (without alpha); in the latter case, you can leverage ETC1 compression.

 

If you require 32-bit compression (with or without alpha) or 16-bit compression (with alpha), then you must leverage PVRTC compression for the Imagination GPU and ATC compression for the Qualcomm GPU.

 

In the case of leveraging separate BAR files per GPU, developers have the opportunity to create two separate BAR (BlackBerry Application Archive) files when submitting to the BlackBerry® World™ storefront; this is specified within BlackBerry World.

 

For a complete outline of this topic, please refer to the following BlackBerry Developer Blog article.

 

Locking Screen Orientation

Each BlackBerry 10 application must contain a config.xml document that defines various properties about the application. Among basic values (application name, author, etc.), this is also where you define BlackBerry / WebWorks specific functionality you will be using via <feature> elements, and application-level settings such as screen orientation.

 

For BlackBerry 10, setting the screen orientation looks as follows:

 

<feature id="blackberry.app">
    <param name="orientation" value="portrait" />
</feature>

 

Viewport Scaling

In many instances, developers will make use of the <meta> viewport element in order to disable features like pinch-to-zoom while ensuring their DOM content is properly scaled. However, if an improper <meta> viewport element is specified within a BlackBerry 10 application, the end result will be improper scaling of many elements, or a zoomed-in appearance.

 

One of the more common <meta> viewport definitions that can result in a zoomed-in  experience is:

 

<meta name="viewport" id="viewport" content="initial-scale=1.0,user-scalable=no,maximum-scale=1.0" />

 

The primary issue is that an initial-scale of 1.0 is based on a standard resolution / pixel density that is not equivalent to BlackBerry 10 devices. Omitting the <meta> viewport will resolve the zoomed-in experience but that leaves developers without the ability to disable pinch-to-zoom.

 

The solution is to calculate the proper initial-scale at runtime based on the device’s pixel density through a <script> element instead. The following would be included within the <head> of a document.

 

<script type="text/javascript">
    var meta = document.createElement('meta');
    meta.setAttribute('name', 'viewport');
    meta.setAttribute('content', 'user-scalable=no,initial-scale=' + (1.0 / window.devicePixelRatio));
document.getElementsByTagName('head')[0].appendChild(meta); </script>

 

Notice that we are relying on the window.devicePixelRatio value in order to set the appropriate initial-scale. This ensures that regardless of the device we are targeting, that we have appropriate <meta> viewport scaling. This also provides the opportunity to add other flags such as user-scalable=no.

 

For a detailed explanation on this approach, please refer to the following Knowledge Base article.

 

Disable Scrolling

Occassionally, you may set the user-scalable=no property but find that your application still allows pinch-to-zoom or panning. This can generally occur in two scenarios:

  • Your content extends beyond the dimensions of the screen; or
  • You have added DOM elements off-screen.

This can cause the viewport to reset and discard the properties you have specified. To avoid this, you can use the following CSS styling on your body to prevent a reset:

 

body {
      position: fixed;
      left: 0px; right: 0px; top: 0px; bottom: 0px;
      border: 0px; margin: 0px; padding: 0px;
      overflow: hidden;
      z-index: 0;
}

 

An alternative would be to set a touchmove event listener on your main document and leverage event.preventDefault() within the event handler, however this can have larger implications on the touch event processing of your application in some cases.

 

User Input

One of the more common issues that arise for WebGL developers is that, due to limited mobile support for WebGL in general, many projects are targeted for the desktop space. This leaves a disconnect in desktop control mechanisms (mouse/keyboard) and mobile control mechanisms (touch/keyboard.) While both domains contain a physical keyboard, WASD or arrow key movement may not directly translate to a mobile device

 

The BlackBerry 10 platform supports multiple touch points and is very open to a variety of user interaction approaches mimicking joysticks and buttons, or relying on raw gestures (swipe, pinch, etc.) and device states (orientation, rotation, etc.)

 

Hammer.js is a popular gesture framework that can be leveraged for many common actions (double tap, swipe, drag, etc.) and a sample is available on Github® under the BlackBerry 10-WebWorks-Samples repository. An overview of this framework can be found at the following BlackBerry Developer Blog article.

 

Hammer.js is fully supported on both the PlayBook and BlackBerry 10 OS. For the resource conscious developer, rest assured the entire framework clocks in at only ~2kb total.

 

While Hammer.js provides gesture processing, Freewill.js was also designed to simplify the joystick and button concept. The goal of this framework is to minimize the effort required to add these components to an overlay within the application. A sample implementation can be found in the tutorials section of the BoxQuest Github sample. For more information, please refer to this BlackBerry Developer Blog article.

 

Of course, these are just a few examples, other frameworks and mechanisms are also available to developers. Device acceleration is a very common input mechanism but is only one of many sensors available on the BlackBerry 10 platform.

 

Packaging and Deploying to BlackBerry 10

In order to convert a folder with HTML5 resources into a BlackBerry 10 application (BAR file) you will need to

For the config.xml document, the file needs to exist at the root folder of your project before it can be packaged. The most basic config.xml looks as follows:

 

<?xml version="1.0" encoding="utf-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
          xmlns:rim="http://www.blackberry.com/ns/widgets"
          version="1.0.0.0"
          id="A_UNIQUE_APP_ID">
 
     <name>Sample App</name>
     <author>Erik Oros</author>
     <content src="index.html" />
     <icon src="icon-114.png" />
</widget>

 

The parts that need to be modified are:

  • The id which is simply a string that is unique to this application.
  • The name and author fields get updated to your own values.
  • The content src points at the HTML file that starts your application (unless you have made modifications, this will be index.html).
  • The icon src references your Application Icon which should be 114x114 pixels.

Once your application is packaged and signed, and you have the resulting BAR file, you can then upload that BAR file to BlackBerry World for distribution. For a step-by-step guide on submitting BlackBerry 10 applications to BlackBerry World, please refer to this video guide.

 

For complete documentation, tools, and resources regarding the BlackBerry WebWorks (HTML5) platform, please refer to http://developer.blackberry.com/html5/.

 

Known Issues

As of BlackBerry 10.0.10.263, the following are not yet supported within the WebGL implementation:

  • Video to texture.
  • DXT compressed textures.
  • Antialiasing is not currently available on the Imagination GPU but is being targeted for a future release.

 Resources

If you have any questions or feedback about this article, please do not hesitate to leave a comment, or reach out via email (eoros@blackberry.com) or Twitter (@WaterlooErik). If you are developing any Three.js applications or games, let me know!

Contributors
Comments
by Developer on ‎08-28-2013 11:30 PM

Eric,

 

I'd like to use texture compression, but to do that we need extension names and internal format codes. The gl.getSupportedExtension() function does not advertise ETC1, PVRTC or ATC support.

 

How should ETC1 compression be used in WebGL? Which extension & internal format codes are available?

 

It does seem to support S3TC in DXT1, DXT3 and DXT5 encoding: it loads the extension with gl.getExtension("WEBKIT_WEBGL_compressed_texture_s3tc"), reports compression formats, even loads the textures, but just renders black.

 

Am I overlooking somehting obvious here?

by BlackBerry Development Advisor on ‎08-29-2013 02:18 PM