Display Access

Accessing the Display

There are two ways of accessing the display:

  1. SDL APIs—A set of 2D APIs that are not hardware accelerated.
  2. OpenGL APIs.

Notes:

You can use either of these for graphics, but NOT both—they are mutually exclusive. SDL is still used for audio and input, even when OpenGL is being used for graphics.

OpenGL function calls are only supported from the main application thread. Behavior is undefined if other threads attempt to interact with OpenGL.

To initialize your application's display:

  1. Call SDL_Init.

    The first thing your SDL application should do is call SDL_Init. This function is passed an unsigned int. Different SDL subsystems are initialized depending on which bits are set in this field. Always pass the pre-defined constant SDL_INIT_VIDEO to ensure the video subsystem is initialized: 

    error = SDL_Init(SDL_INIT_VIDEO);

  2. Configure your display frame buffer.

    Specify the OpenGL ES version you are using. If you are using OpenGL ES 1.1, you should specify the major version as 1; for OpenGL ES 2.0, use 2: 

    SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 1);

    If you need stencil or depth buffers, initialize them here as well. For example: 

    //** Set depth buffer size to 16 bits
SDL_GL_SetAttribute( SDL_GL_DEPTH_SIZE, 16 );

//** Set stencil buffer size to 16 bits
SDL_GL_SetAttribute( SDL_GL_STENCIL_SIZE, 16 );

  3. Set the video mode.

    Unless you are running on the device, set the desktop app's resolution to that of your target device (320 x 480 for Pre, 320 x 400 for Pixi) and specify the SDL_OPENGL flag to initialize openGL: 

    //** When running on the device, use a resolution of 0x0-the
//** application is automatically fullscreen
#if ON_DEVICE
  SDL_SetVideoMode(0, 0, 0, SDL_OPENGL);
#else
  SDL_SetVideoMode(320, 480, 0, SDL_OPENGL);
#endif

Note:

The SDL_FULLSCREEN flag has no effect when running on the device. We do not recommend its use.

Setting up Your Frustum

When setting up your application's frustum (the three-dimensional region visible on the screen), keep in mind the following:

  • webOS supports devices with different aspect ratios. For forward compatibility with future devices, your application should support different screen sizes. Accordingly, you should use the screen dimensions to set up your view. You can find the screen dimensions using the SDL_GetVideoInfo() call.

  • If you are coding an app that normally runs in landscape mode, you are likely to be rotating the outputted display data. However, to test the same program in a desktop environment, you will not want to rotate it. We recommend making your rotation conditional based on the platform—desktop or device.

Alpha Blending

Alpha blending is the process of combining (aka compositing) a translucent foreground color with a background color, thereby producing a new blended color. The degree of the foreground color's translucency may range from completely transparent to completely opaque. If the foreground color is completely transparent, the blended color becomes the background color. Conversely, if it is completely opaque, the blended color becomes the foreground color. The translucency can also range between these extremes, in which case the blended color is computed as a weighted average of the foreground and background colors.

One of the things that differentiates the Palm platform from others is an alpha channel in the destination frame buffer. This allows you to set, for each pixel, not only the red, green, and blue values, but also the alpha value, which can range from 0 (completely transparent) to 1 (completely opaque).

On webOS devices, there are two hardware layers that are blended together using RGB and alpha values:

Blended hardware layers

image

To enable video playback, you can set the alpha value of your App layer to allow the lower video layer to show through. If you are using the standard alpha blending equation (in GL this means using a glBlendFunc of GL_SRC_ALPHA, or GL_ONE_MINUS_SRC_ALPHA):

image

Or, in other words: 

Destination alpha = (Source alpha * Source alpha)
  + (Destination alpha * (1 - Source alpha))

Then, there is a danger where the alpha values themselves are blended.

For example, using this equation, if your destination alpha is 1.0, and the source alpha is 0.3 for a primitive (point, line, triangle, etc.), any pixels that are blended will have the following alpha: 

(0.3 * 0.3) + (1.0 * (0.7)) = 0.79.

The destination layer now has an alpha of less than 1.0 and the video layer can bleed through. If the video layer is black, for example, it will cause your texture to seem darker.

Even if you are not using video, you should be aware of this, because even if there is no video playing, the video layer still consists of random bits (not necessarily black) which can bleed through.

One way around this is to use a Porter-Duff color model (GL_ONE, GL_ONE_MINUS_SRC_ALPHA) with pre-multiplied values. A discussion of the Porter-Duff model is beyond the scope of this document, but see http://en.wikipedia.org/wiki/Alpha_compositing or other sources for more information.

To have your application display completely opaque, you can clear the frame buffer each time, setting the alpha to 1.0 and disable writing to the alpha channel when you draw the rest of the scene.

To have your application display without blending with the video layer, specify that alpha cannot be written into the frame buffer: 

glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_FALSE);

Supported Texture Compression Formats

Texture compression is a specialized form of image compression designed for storing texture maps in 3D computer graphics rendering systems. webOS devices support the following GL compression formats:

Pre and Pixi 

GL_OES_compressed_ETC1_RGB8_textureGL_OES_compressed_paletted_textureGL_ETC1_RGB8_OES

Pre 

GL_COMPRESSED_RGB_PVRTC_4BPPV1_IMG GL_COMPRESSED_RGB_PVRTC_2BPPV1_IMG GL_COMPRESSED_RGBA_PVRTC_4BPPV1_IMG GL_COMPRESSED_RGBA_PVRTC_2BPPV1_IMG

Pixi 

GL_ATC_RGB_AMDGL_ATC_RGBA_EXPLICIT_ALPHA_AMD GL_ATC_RGBA_INTERPOLATED_ALPHA_AMD

We recommend you use the compression formats that can be used on both the Pre and Pixi.

Disabling Screen Dimming

By default, for fullscreen apps, the screen never dims. You can use the PDL_ScreenTimeoutEnable call to enable or disable the screen dimming timeout when your application is running fullscreen.