FDO RFC 1 - Support Raster Property BitsUsedPerPixel

This page contains a change request (RFC) for the FDO Open Source project. More FDO RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	Mar 13, 2007
Last Modified	Greg BooneTimestamp
Author	Greg Boone
RFC Status	Withdrawn
Implementation Status	Withdrawn
Proposed Milestone	N/A
Assigned PSC guide(s)	Greg Boone
Voting History	TBD
+1
+0
-0
-1

Overview

The purpose of this RFC is to allow FDO users to determine the number of bits used per pixel when interfacing with FDO providers that support the FdoIRaster and FdoIRasterDataModel interface.

Motivation

The FDO API FdoRasterDataModel class currently includes a property to determine the number of bits per pixel returned in an FdoIRaster data stream. The FdoIRaster data stream contains the raw raster image data.

/ \brief
/ The FdoRasterDataModel specifies the data type and organization
/ of raster data retrieved and stored. Using this class and the image
/ extents in width and length, the binary format of the image data returned
/ by and accepted by the FdoIStreamReader class can be interpreted.
class FdoRasterDataModel: public FdoIDisposable
{
public:

…
…

/ \brief
/ Get the number of bits per pixel.
/
/ \return
/ Returns the number of bits for each pixel. For multi-channel
/ data the bits per channel will be this value devided by the numer of
/ channels. For example, RGB data has three channels, so if this
/ method returns twelve, each channel is four bits.
/
FDO_API virtual !FdoInt32 GetBitsPerPixel ();

/ \brief
/ Set the number of bits per pixel.
/
/ \param bpp
/ The number of bits per pixel desired.
/ Values of 1, 4, 8, 16, 24, 32, 48 and 64 bits per channel may
/ be supported. Others values (i.e. indivisible by the number of channels)
/ are likely to raise a FdoException.
/
FDO_API virtual void SetBitsPerPixel (!FdoInt32 bpp);

…
…

};

However, returning only the bits per pixel is not sufficient to quickly and efficiently process the raster stream. The user should also be made aware of the bits used per pixel. In certain circumstances, the raster image does not completely use all available bits and pads the extra bits in the raster stream with NULL values. Without knowing the bits used per pixel, the client has to spend processing cycles determining how many bits are used thus affecting the performance of their applications.

This issue was identified by IKonus, a corporate user of the FDO API.

Proposed Solution

The FDO FdoRasterDataModel class will be extended to export the number of bits used per pixel.

/ \brief
/ The FdoRasterDataModel specifies the data type and organization
/ of raster data retrieved and stored. Using this class and the image
/ extents in width and length, the binary format of the image data returned
/ by and accepted by the FdoIStreamReader class can be interpreted.
class FdoRasterDataModel: public !FdoIDisposable
{
public:

…
…

/ \brief
/ Get the number of bits per pixel.
/
/ \return
/ Returns the number of bits for each pixel. For multi-channel
/ data the bits per channel will be this value devided by the numer of
/ channels. For example, RGB data has three channels, so if this
/ method returns twelve, each channel is four bits.
/
FDO_API virtual !FdoInt32 GetBitsPerPixel ();

/ \brief
/ Set the number of bits per pixel.
/
/ \param bpp
/ The number of bits per pixel desired.
/ Values of 1, 4, 8, 16, 24, 32, 48 and 64 bits per channel may
/ be supported. Others values (i.e. indivisible by the number of channels)
/ are likely to raise an FdoException.
/
FDO_API virtual void SetBitsPerPixel (!FdoInt32 bpp);

/ \brief
/ Get the number of bits used per pixel.
/
/ \return
/ Returns the number of bits used for each pixel. For multi-channel
/ data the bits used per channel will be this value devided by the numer of
/ channels. For example, RGB data has three channels, so if this
/ method returns twelve, each channel uses four bits.
/
FDO_API virtual !FdoInt32 GetBitsUsedPerPixel ();

/ \brief
/ Set the number of bits used per pixel.
/
/ \param bpp
/ The number of bits per used per pixel.
/
/ \remarks
/ This method is primarily being defined for object construction purposes
/ within the provider and would not be called by client applications.
FDO_API virtual void SetBitsUsedPerPixel (!FdoInt32 bpp);

…
…

};

The new property will also be added to the FDO Managed API.

Notes

This API change is applicable for all raster formats. Image formats who do not explicitly advertise their bitsUserPerPixel will have this value set to the value of bitsPerPixel.

This ECO is being written in order to better support ongoing development using the FDO Raster providers. Existing customers such as AutoCAD Map and MapGuide have implemented work-arounds to calculate the bitsUsedPerPixel manually. While this calculation affects performance, the cost is slight.

Test Plan

Raster Provider unit tests should be expanded to include usage of the new GetBitsUsedPerPixel Property

Impact of Not Implementing this ECO

If this ECO is not implemented, clients such as IKonus will have to calculate the number of bits used manually and accept the impact on performance.

Funding/Resources

Autodesk to provide resources / funding.