Image +Compatibility Use Cases

Variant: ScreenPlay. Target +audience: Device creators.

The use cases are:

Constant images
Application-level CPU rendering
Off-screen rendering
UI surface rendering

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:

+ + + +

EUidPixelFormatARGB_8888_PRE

+ + +

EUidPixelFormatXRGB_8888

+ + +

EUidPixelFormatARGB_8888

+ + +

EUidPixelFormatRGB_565

+ + + +

* 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:

+ + + +

RSgImage::MapReadOnly()

Makes pixel data accessible for reading by the CPU

+ + +

RSgImage::MapWriteOnly()

Makes pixel data accessible for writing by the CPU

+ + +

RSgImage::MapReadWrite()

Makes pixel data accessible for reading and writing by the CPU

+ + +

RSgImage::Unmap()

Makes pixel data not accessible for reading or writing by the CPU

+ + + +

The pixel formats supported for this use case are:

+ + + +

EUidPixelFormatARGB_8888_PRE

+ + +

EUidPixelFormatXRGB_8888

+ + +

EUidPixelFormatRGB_565

+ + + +

* 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:

+ + + +

At least one RGB format with an alpha channel, and a minimum +of 8 bits per channel. Channel ordering is not specified

+ + +

At least one RGB format with no alpha channel, and a minimum +of 8 bits per channel. Channel ordering is not specified.

+ + + +

* 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:

+ + + +

At least one RGB format with an alpha channel, and a minimum +of 8 bits per channel. Channel ordering is not specified.

+ + + +

* If DirectGDI is present on the platform.

** If OpenGL +ES is present on the platform.

*** If OpenVG is present on the platform.