Image Compatibility Use Cases

Constant images

A constant image is not modified after creation. A typical example of a constant image is an icon that is loaded from a file and does not change.

A constant image has the following guaranteed set of attributes:

• The image cannot be changed.

• Applications cannot have direct access to the pixels (no CPU access).

• The image may only be used as a source for DirectGDI* or CWindowGc rendering.

• The screen ID can be -1 or the ID of a screen on the phone. For example, on a device that has a single screen, it can be -1 or 0. -1 indicates "screen agnostic", which means that the image can be rendered on any screen. This is the only use case for which this is guaranteed.

• The pixel size can be any size, subject to memory available for use.

• The image may be sharable or non-sharable.

A constant image is one that is created with no request for CPU write access and no request for use as a rendering target. For more information, see TSgImageInfo.

This use case covers images created using RSgImage::Create() where the user provides the initial data.

The pixel formats supported for this use case are:

* If DirectGDI is present on the platform.

Application-level CPU rendering

This use case corresponds to an image that is modified directly by an application, without the use of rendering functions provided by the platform. For example, a game that uses its own rendering functions.

The set of guaranteed attributes for this type of image are:

• The image can be changed (it is mutable).

• The application can have direct read and write access to the pixel data.

• Support is only guaranteed for usage as a source for DirectGDI* or CWindowGc rendering.

• Support is only guaranteed if the image is tied to one screen. The screen ID must therefore be the actual ID of one of the screens on the device. If the image needs to be used on multiple screens, multiple copies of the image may be required.

• The image size (size in pixels) is limited only by memory availability.

• The image may be sharable or non-sharable.

To allow the CPU to access the pixel data, a developer can use the following functions:

The pixel formats supported for this use case are:

* If DirectGDI is present on the platform.

Off-screen rendering

This use case corresponds to images that are used to store the results of rendering pipelines provided by the platform; for example DirectGDI, OpenGLES or OpenVG.

The set of guaranteed attributes for this type of image are:

• The image can be changed (it is mutable)

• The application cannot have direct access to the pixels on the image to read or write (no CPU access)

• The image can be used as a:

  • Target for DirectGDI*, OpenGLES** or OpenVG*** rendering.

  • Source for DirectGDI* or CWindowGc rendering.

• Support is only guaranteed if the image is tied to one screen. The screen ID must therefore be the actual ID of one of the screens on the device. If the image needs to be used on multiple screens, multiple copies of the image may be required.

• The image size (in pixels) is limited only by memory availability

• The image may be sharable or non-sharable.

The pixel formats supported for this use case are:

* If DirectGDI is present on the platform.

** If OpenGL ES is present on the platform.

*** If OpenVG is present on the platform.

UI surface rendering

This use case corresponds to an image that is created by the Window Server to transfer UI rendering into the composition engine. This use case only applies to the creation of RSgImageCollection instances.

The set of guaranteed attributes for this type of image are:

• The image can be changed (it is mutable)

• The user does not require direct access to the image pixels (no CPU access)

• The image can be used as a:

  • Target for DirectGDI*, OpenGLES** or OpenVG*** rendering

  • Composition source, which means that it is used as input to the composition engine

  • Screen source, which means that the display hardware can read it directly

• Support is only guaranteed if the image is tied to one screen. The screen ID must therefore be the actual ID of one of the screens on the device.

• The image size must be supported by the specified screen.

• The image is not shareable between processes.

The pixel formats supported for this use case are:

* If DirectGDI is present on the platform.

** If OpenGL ES is present on the platform.

*** If OpenVG is present on the platform.