class GBitmap: public GPEnabled

Bilevel and gray-level images.

Inheritance:


Public

[more] Construction.

[more] GBitmap()
Constructs an empty GBitmap object.
[more] GBitmap(int nrows, int ncolumns, int border=0)
Constructs a GBitmap with nrows rows and ncolumns columns.
[more] GBitmap(const GBitmap &ref)
Copy constructor.
[more] GBitmap(const GBitmap &ref, int border)
Constructs a GBitmap by copying the contents of GBitmap ref.
[more] GBitmap(const GBitmap &ref, const GRect &rect, int border=0)
Constructs a GBitmap by copying a rectangular segment rect of GBitmap ref.
[more] GBitmap(ByteStream &ref, int border=0)
Constructs a GBitmap by reading PBM, PGM or RLE data from ByteStream ref into this GBitmap.

[more] Initialization.

[more]void init(int nrows, int ncolumns, int border=0)
Resets this GBitmap size to nrows rows and ncolumns columns and sets all pixels to white.
[more]void init(const GBitmap &ref, int border=0)
Initializes this GBitmap with the contents of the GBitmap ref.
[more]void init(const GBitmap &ref, const GRect &rect, int border=0)
Initializes this GBitmap with a rectangular segment rect of GBitmap ref.
[more]void init(ByteStream &ref, int border=0)
Reads PBM, PGM or RLE data from ByteStream ref into this GBitmap.
[more]GBitmap& operator=(const GBitmap &ref)
Assignment operator.
[more]void fill(unsigned char value)
Initializes all the GBitmap pixels to value value.

[more] Accessing the pixels.

[more]unsigned int rows() const
Returns the number of rows (the image height).
[more]unsigned int columns() const
Returns the number of columns (the image width).
[more]const unsigned char* operator[] (int row) const
Returns a constant pointer to the first byte of row row.
[more]unsigned char* operator[] (int row)
Returns a pointer to the first byte of row row.
[more]unsigned int rowsize() const
Returns the size of a row in memory (in pixels).
[more]void minborder(int minimum)
Makes sure that the border is at least minimum pixels large.

[more] Managing gray levels.

[more]int get_grays() const
Returns the number of gray levels.
[more]void set_grays(int grays)
Sets the number of gray levels without changing the pixels.
[more]void change_grays(int grays)
Changes the number of gray levels.
[more]void binarize_grays(int threshold=0)
Binarizes a gray level image using a threshold.

[more] Optimizing the memory usage.

[more]void compress()
Reduces the memory required for a bilevel image by using a run-length encoded representation.
[more]unsigned int get_memory_usage() const
Returns the number of bytes allocated for this image.

[more] Additive Blit.

[more]void blit(const GBitmap *bm, int x, int y)
Performs an additive blit of the GBitmap bm.
[more]void blit(const GBitmap *shape, int x, int y, int subsample)
Performs an additive blit of the GBitmap bm with anti-aliasing.

[more] Saving images.

[more]void save_pbm(ByteStream &bs, int raw=1)
Saves the image into ByteStream bs using the PBM format.
[more]void save_pgm(ByteStream &bs, int raw=1)
Saves the image into ByteStream bs using the PGM format.
[more]void save_rle(ByteStream &bs)
Saves the image into ByteStream bs using the RLE file format.

[more] Stealing or borrowing the memory buffer (advanced).

[more]unsigned char* take_data(size_t &offset)
Steals the memory buffer of a GBitmap.
[more]void borrow_data(unsigned char *data, int w, int h)
Initializes this GBitmap by borrowing a memory segment.


Inherited from GPEnabled:

Public Methods

oGPEnabled& operator=(const GPEnabled & obj)

Protected Fields

ovolatile int count

Protected Methods

ovirtual void destroy()


Documentation

Bilevel and gray-level images. Instances of class GBitmap represent bilevel or gray-level images. Images are usually represented using one byte per pixel. Value zero represents a white pixel. A value equal to the number of gray levels minus one represents a black pixel. The number of gray levels is returned by the function get_grays and can be manipulated by the functions set_grays and change_grays.

The bracket operator returns a pointer to the bytes composing one line of the image. This pointer can be used to read or write the image pixels. Line zero represents the bottom line of the image.

The memory organization is setup in such a way that you can safely read a few pixels located in a small border surrounding all four sides of the image. The width of this border can be modified using the function minborder. The border pixels are initialized to zero and therefore represent white pixels. You should never write anything into border pixels because they are shared between images and between lines.

o Construction.

o GBitmap()
Constructs an empty GBitmap object. The returned GBitmap has zero rows and zero columns. Use function init to change the size of the image.

o GBitmap(int nrows, int ncolumns, int border=0)
Constructs a GBitmap with nrows rows and ncolumns columns. All pixels are initialized to white. The optional argument border specifies the size of the optional border of white pixels surrounding the image. The number of gray levels is initially set to 2.

o GBitmap(const GBitmap &ref)
Copy constructor. Constructs a GBitmap by replicating the size, the border and the contents of GBitmap ref.

o GBitmap(const GBitmap &ref, int border)
Constructs a GBitmap by copying the contents of GBitmap ref. Argument border specifies the width of the optional border.

o GBitmap(const GBitmap &ref, const GRect &rect, int border=0)
Constructs a GBitmap by copying a rectangular segment rect of GBitmap ref. The optional argument border specifies the size of the optional border of white pixels surrounding the image.

o GBitmap(ByteStream &ref, int border=0)
Constructs a GBitmap by reading PBM, PGM or RLE data from ByteStream ref into this GBitmap. The optional argument border specifies the size of the optional border of white pixels surrounding the image. See PNM and RLE file formats for more information.

o Initialization.

ovoid init(int nrows, int ncolumns, int border=0)
Resets this GBitmap size to nrows rows and ncolumns columns and sets all pixels to white. The optional argument border specifies the size of the optional border of white pixels surrounding the image. The number of gray levels is initialized to 2.

ovoid init(const GBitmap &ref, int border=0)
Initializes this GBitmap with the contents of the GBitmap ref. The optional argument border specifies the size of the optional border of white pixels surrounding the image.

ovoid init(const GBitmap &ref, const GRect &rect, int border=0)
Initializes this GBitmap with a rectangular segment rect of GBitmap ref. The optional argument border specifies the size of the optional border of white pixels surrounding the image.

ovoid init(ByteStream &ref, int border=0)
Reads PBM, PGM or RLE data from ByteStream ref into this GBitmap. The previous content of the GBitmap object is lost. The optional argument border specifies the size of the optional border of white pixels surrounding the image. See PNM and RLE file formats for more information.

oGBitmap& operator=(const GBitmap &ref)
Assignment operator. Initializes this GBitmap by copying the size, the border and the contents of GBitmap ref.

ovoid fill(unsigned char value)
Initializes all the GBitmap pixels to value value.

o Accessing the pixels.

ounsigned int rows() const
Returns the number of rows (the image height).

ounsigned int columns() const
Returns the number of columns (the image width).

oconst unsigned char* operator[] (int row) const
Returns a constant pointer to the first byte of row row. This pointer can be used as an array to read the row elements.

ounsigned char* operator[] (int row)
Returns a pointer to the first byte of row row. This pointer can be used as an array to read or write the row elements.

ounsigned int rowsize() const
Returns the size of a row in memory (in pixels). This number is equal to the difference between pointers to pixels located in the same column in consecutive rows. This difference can be larger than the number of columns in the image.

ovoid minborder(int minimum)
Makes sure that the border is at least minimum pixels large. This function does nothing it the border width is already larger than minimum. Otherwise it reorganizes the data in order to provide a border of minimum pixels.

o Managing gray levels.

oint get_grays() const
Returns the number of gray levels. Value 2 denotes a bilevel image.

ovoid set_grays(int grays)
Sets the number of gray levels without changing the pixels. Argument grays must be in range 2 to 256.

ovoid change_grays(int grays)
Changes the number of gray levels. The argument grays must be in the range 2 to 256. All the pixel values are then rescaled and clipped in range 0 to grays-1.

ovoid binarize_grays(int threshold=0)
Binarizes a gray level image using a threshold. The number of gray levels is reduced to 2 as in a bilevel image. All pixels whose value was strictly greater than threshold are set to black. All other pixels are set to white.

o Optimizing the memory usage.
The amount of memory used by bilevel images can be reduced using function compress, which encodes the image using a run-length encoding scheme. The bracket operator decompresses the image on demand. A few highly optimized functions (e.g. blit) can use a run-length encoded bitmap without decompressing it.

ovoid compress()
Reduces the memory required for a bilevel image by using a run-length encoded representation. Functions that need to access the pixel array will decompress the image on demand.

ounsigned int get_memory_usage() const
Returns the number of bytes allocated for this image.

o Additive Blit.
The blit functions are designed to efficiently construct an anti-aliased image by copying smaller images at predefined locations. The image of a page, for instance, is composed by copying the images of characters at predefined locations. These functions are fairly optimized. They can directly use compressed GBitmaps (see compress). We consider in this section that each GBitmap comes with a coordinate system defined as follows. Position (0,0) corresponds to the bottom left corner of the bottom left pixel. Position (1,1) corresponds to the top right corner of the bottom left pixel, which is also the bottom left corner of the second pixel of the second row. Position (w,h), where w and h denote the size of the GBitmap, corresponds to the top right corner of the top right pixel.

ovoid blit(const GBitmap *bm, int x, int y)
Performs an additive blit of the GBitmap bm. The GBitmap bm is first positioned above the current GBitmap in such a way that position (u,v) in GBitmap bm corresponds to position (u+x,v+y) in the current GBitmap. The value of each pixel in GBitmap bm is then added to the value of the corresponding pixel in the current GBitmap.

Example: Assume for instance that the current GBitmap is initially white (all pixels have value zero). This operation copies the pixel values of GBitmap bm at position (x,y) into the current GBitmap. Note that function blit does not change the number of gray levels in the current GBitmap. You may have to call set_grays to specify how the pixel values should be interpreted.

ovoid blit(const GBitmap *shape, int x, int y, int subsample)
Performs an additive blit of the GBitmap bm with anti-aliasing. The GBitmap bm is first positioned above the current GBitmap in such a way that position (u,v) in GBitmap bm corresponds to position (u+x/subsample,v+y/subsample) in the current GBitmap. This mapping results in a contraction of GBitmap bm by a factor subsample. Each pixel of the current GBitmap can be covered by a maximum of subsample^2 pixels of GBitmap bm. The value of each pixel in GBitmap bm is then added to the value of the corresponding pixel in the current GBitmap.

Example: Assume for instance that the current GBitmap is initially white (all pixels have value zero). Each pixel of the current GBitmap then contains the sum of the gray levels of the corresponding pixels in GBitmap bm. There are up to subsample*subsample such pixels. If for instance GBitmap bm is a bilevel image (pixels can be 0 or 1), the pixels of the current GBitmap can take values in range 0 to subsample*subsample. Note that function blit does not change the number of gray levels in the current GBitmap. You must call set_grays to indicate that there are subsample^2+1 gray levels. Since there is at most 256 gray levels, this also means that subsample should never be greater than 15.

Remark: Arguments x and y do not represent a position in the coordinate system of the current GBitmap. According to the above discussion, the position is (x/subsample,y/subsample). In other words, you can position the blit with a sub-pixel resolution. The resulting anti-aliasing changes are paramount to the image quality.

o Saving images.
The following functions write PBM, PGM and RLE files. PBM and PGM are well known formats for bilevel and gray-level images. The RLE is a simple run-length encoding scheme for bilevel images. These files can be read using the ByteStream based constructor or initialization function. See PNM and RLE file formats for more information.

ovoid save_pbm(ByteStream &bs, int raw=1)
Saves the image into ByteStream bs using the PBM format. Argument raw selects the ``Raw PBM'' (1) or the ``Ascii PBM'' (0) format. The image is saved as a bilevel image. All non zero pixels are considered black pixels. See section PNM and RLE file formats.

ovoid save_pgm(ByteStream &bs, int raw=1)
Saves the image into ByteStream bs using the PGM format. Argument raw selects the ``Raw PGM'' (1) or the ``Ascii PGM'' (0) format. The image is saved as a gray level image. See section PNM and RLE file formats.

ovoid save_rle(ByteStream &bs)
Saves the image into ByteStream bs using the RLE file format. The image is saved as a bilevel image. All non zero pixels are considered black pixels. See section PNM and RLE file formats.

o Stealing or borrowing the memory buffer (advanced).

ounsigned char* take_data(size_t &offset)
Steals the memory buffer of a GBitmap. This function returns the address of the memory buffer allocated by this GBitmap object. The offset of the first pixel in the bottom line is written into variable offset. Other lines can be accessed using pointer arithmetic (see rowsize). The GBitmap object no longer ``owns'' the buffer: you must explicitly de-allocate the buffer using operator delete []. This de-allocation should take place after the destruction or the re-initialization of the GBitmap object. This function will return a null pointer if the GBitmap object does not ``own'' the buffer in the first place.

ovoid borrow_data(unsigned char *data, int w, int h)
Initializes this GBitmap by borrowing a memory segment. The GBitmap then directly addresses the memory buffer data provided by the user. This buffer must be large enough to hold w*h bytes. The GBitmap object does not ``own'' the buffer: you must explicitly de-allocate the buffer using operator delete []. This de-allocation should take place after the destruction or the re-initialization of the GBitmap object.


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java