A handle to a reference-counted, bi-dimensional pixel array that can be used for various purposes, such as being a source or a target of different rendering pipelines, according to its attributes, which are set at creation time and cannot be changed afterwards.

An image can be shared between processes by passing its unique identifier across. Alternatively it can be created as not shareable, or process-specific, and this may have performance advantages. Sharing is achieved by using the value returned by Id() in a call to Open() on another instance of RSgImage to open a new handle to the image. Since images are reference-counted they are guaranteed to exist while there are open handles referencing them.

An image can be created for use with any screen. Alternatively it can be created as screen-specific and this may have performance advantages.

An image can be created as mappable. This means that the CPU can potentially read and/or write directly to the pixel data. It is recommended to use mappable images only when absolutely necessary because they can be less efficient than non-mappable images.

An image can be created as constant or mutable. Constant images, also known as immutable images, do not allow modification after creation and this may have performance advantages. A mutable image can be modified after creation, e.g. by using it as a rendering target. A constant image cannot be used as a rendering target.

A new RSgImage handle does not refer to an image until a successful call to Create() or Open() . Before that point, the handle is said to be a null handle. Instances of RSgImage can be shared among threads in the same process.

An RSgImage handle is said to be invalid if it is not null but it does not reference an existing image. Copying an instance of RSgImage must be done with extreme care, since it does not increment the reference count of the referenced image and may therefore allow some RSgImage handle to become invalid when the image is destroyed.