• Skip to content
  • Skip to link menu
KDE 3.5 API Reference
  • KDE API Reference
  • API Reference
  • Sitemap
  • Contact Us
 

kviewshell

GBitmap Class Reference

Bilevel and gray-level images. More...

#include <GBitmap.h>

Inheritance diagram for GBitmap:

Inheritance graph
[legend]

List of all members.


Public Types

enum  { RUNOVERFLOWVALUE = 0xc0 }
enum  { RUNMSBMASK = 0x3f }
enum  { RUNLSBMASK = 0xff }
enum  { MAXRUNSIZE = 0x3fff }

Public Member Functions

void check_border () const
void destroy (void)
virtual ~GBitmap ()
Managing gray levels.
void binarize_grays (int threshold=0)
void change_grays (int grays)
int get_grays () const
void set_grays (int grays)
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.

void blit (const GBitmap *shape, int x, int y, int subsample)
void blit (const GBitmap *bm, int x, int y)
Accessing the pixels.
unsigned int columns () const
void minborder (int minimum)
unsigned char * operator[] (int row)
const unsigned char * operator[] (int row) const
unsigned int rows () const
unsigned int rowsize () const
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. There are unfortunate locking issues associated with this capability (c.f. {share} and {monitor}).

void compress ()
unsigned int get_memory_usage () const
GMonitor * monitor () const
void share ()
void uncompress ()
Initialization.
void fill (unsigned char value)
void init (ByteStream &ref, int border=0)
void init (const GBitmap &ref, const GRect &rect, int border=0)
void init (const GBitmap &ref, int border=0)
void init (int nrows, int ncolumns, int border=0)
GBitmap & operator= (const GBitmap &ref)
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.

void save_pbm (ByteStream &bs, int raw=1)
void save_pgm (ByteStream &bs, int raw=1)
void save_rle (ByteStream &bs)

Static Public Member Functions

Construction.
static GP< GBitmap > create (ByteStream &ref, const int border=0)
static GP< GBitmap > create (const GBitmap &ref, const GRect &rect, const int border=0)
static GP< GBitmap > create (const GBitmap &ref, const int border)
static GP< GBitmap > create (const GBitmap &ref)
static GP< GBitmap > create (const int nrows, const int ncolumns, const int border=0)
static GP< GBitmap > create (void)

Public Attributes

GP< ZeroBuffer > gzerobuffer

Protected Member Functions

 GBitmap (ByteStream &ref, int border=0)
 GBitmap (const GBitmap &ref, const GRect &rect, int border=0)
 GBitmap (const GBitmap &ref, int border)
 GBitmap (const GBitmap &ref)
 GBitmap (int nrows, int ncolumns, int border=0)
 GBitmap (void)

Protected Attributes

unsigned short border
unsigned char * bytes
unsigned char * bytes_data
unsigned short bytes_per_row
GPBuffer< unsigned char > gbytes_data
unsigned short grays
GPBuffer< unsigned char > grle
GPBuffer< unsigned char * > grlerows
unsigned short ncolumns
unsigned short nrows
unsigned char * rle
unsigned int rlelength
unsigned char ** rlerows

Stealing or borrowing the memory buffer (advanced).

void borrow_data (unsigned char &data, int w, int h)
void donate_data (unsigned char *data, int w, int h)
void donate_rle (unsigned char *rledata, unsigned int rledatalen, int w, int h)
const unsigned char * get_rle (unsigned int &rle_length)
GP< GBitmap > rotate (int count=0)
unsigned char * take_data (size_t &offset)
static void append_run (unsigned char *&data, int count)
static int read_run (unsigned char *&data)
static int read_run (const unsigned char *&data)

Accessing RLE data.

The next functions are useful for processing bilevel images encoded using the run length encoding scheme.

These functions always return zero if the bitmap is not RLE encoded. Function {compress} must be used to ensure that the bitmap is RLE encoded.

int rle_get_bits (int rowno, unsigned char *bits) const
int rle_get_rect (GRect &rect) const
int rle_get_runs (int rowno, int *rlens) const
static void rle_get_bitmap (const int ncolumns, const unsigned char *&runs, unsigned char *bitmap, const bool invert)

Detailed Description

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.

Definition at line 128 of file GBitmap.h.


Member Enumeration Documentation

anonymous enum

Enumerator:
RUNOVERFLOWVALUE 

Definition at line 449 of file GBitmap.h.

anonymous enum

Enumerator:
RUNMSBMASK 

Definition at line 450 of file GBitmap.h.

anonymous enum

Enumerator:
RUNLSBMASK 

Definition at line 451 of file GBitmap.h.

anonymous enum

Enumerator:
MAXRUNSIZE 

Definition at line 448 of file GBitmap.h.


Constructor & Destructor Documentation

GBitmap::GBitmap ( void   )  [protected]

Definition at line 99 of file GBitmap.cpp.

GBitmap::GBitmap ( int  nrows,
int  ncolumns,
int  border = 0 
) [protected]

Definition at line 107 of file GBitmap.cpp.

GBitmap::GBitmap ( const GBitmap &  ref  )  [protected]

Definition at line 143 of file GBitmap.cpp.

GBitmap::GBitmap ( const GBitmap &  ref,
int  border 
) [protected]

Definition at line 161 of file GBitmap.cpp.

GBitmap::GBitmap ( const GBitmap &  ref,
const GRect &  rect,
int  border = 0 
) [protected]

Definition at line 180 of file GBitmap.cpp.

GBitmap::GBitmap ( ByteStream &  ref,
int  border = 0 
) [protected]

Definition at line 125 of file GBitmap.cpp.

GBitmap::~GBitmap (  )  [virtual]

Definition at line 85 of file GBitmap.cpp.


Member Function Documentation

void GBitmap::append_run ( unsigned char *&  data,
int  count 
) [inline, static]

Static function for generating run data.

This function encoded run length count# at position data# and increments the pointer accordingly. The pointer must initially point to a large enough data buffer.

Definition at line 638 of file GBitmap.h.

void GBitmap::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.

Definition at line 512 of file GBitmap.cpp.

void GBitmap::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.

Definition at line 621 of file GBitmap.cpp.

void GBitmap::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.

Definition at line 546 of file GBitmap.cpp.

void GBitmap::borrow_data ( unsigned char &  data,
int  w,
int  h 
) [inline]

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 representing each one pixel. 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.

Definition at line 659 of file GBitmap.h.

void GBitmap::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#.

Definition at line 486 of file GBitmap.cpp.

void GBitmap::check_border (  )  const

Definition at line 1629 of file GBitmap.cpp.

unsigned int GBitmap::columns (  )  const [inline]

Returns the number of columns (the image width).

Definition at line 550 of file GBitmap.h.

void GBitmap::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.

Definition at line 394 of file GBitmap.cpp.

static GP<GBitmap> GBitmap::create ( ByteStream &  ref,
const int  border = 0 
) [inline, static]

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.

Definition at line 174 of file GBitmap.h.

static GP<GBitmap> GBitmap::create ( const GBitmap &  ref,
const GRect &  rect,
const int  border = 0 
) [inline, static]

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.

Definition at line 167 of file GBitmap.h.

static GP<GBitmap> GBitmap::create ( const GBitmap &  ref,
const int  border 
) [inline, static]

Constructs a GBitmap by copying the contents of GBitmap ref#.

Argument border# specifies the width of the optional border.

Definition at line 161 of file GBitmap.h.

static GP<GBitmap> GBitmap::create ( const GBitmap &  ref  )  [inline, static]

Copy constructor.

Constructs a GBitmap by replicating the size, the border and the contents of GBitmap ref#.

Definition at line 156 of file GBitmap.h.

static GP<GBitmap> GBitmap::create ( const int  nrows,
const int  ncolumns,
const int  border = 0 
) [inline, static]

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#.

Definition at line 151 of file GBitmap.h.

static GP<GBitmap> GBitmap::create ( void   )  [inline, static]

Constructs an empty GBitmap object.

The returned GBitmap has zero rows and zero columns. Use function {init} to change the size of the image.

Definition at line 145 of file GBitmap.h.

void GBitmap::destroy ( void   ) 

Reimplemented from GPEnabled.

Definition at line 90 of file GBitmap.cpp.

void GBitmap::donate_data ( unsigned char *  data,
int  w,
int  h 
)

Same as borrow_data, except GBitmap will call delete[]#.

Definition at line 343 of file GBitmap.cpp.

void GBitmap::donate_rle ( unsigned char *  rledata,
unsigned int  rledatalen,
int  w,
int  h 
)

Initializes this GBitmap by setting the size to h# rows and w# columns, and directly addressing the memory buffer rledata# provided by the user.

This buffer contains rledatalen# bytes representing the bitmap in run length encoded form. The GBitmap object then ``owns'' the buffer (unlike borrow_data#, but like donate_data#) and will deallocate this buffer when appropriate: you should not deallocate this buffer yourself. The encoding of buffer rledata# is similar to the data segment of the RLE file format (without the header) documented in {PNM and RLE file formats}.

Definition at line 357 of file GBitmap.cpp.

void GBitmap::fill ( unsigned char  value  ) 

Initializes all the GBitmap pixels to value value#.

Definition at line 1467 of file GBitmap.cpp.

int GBitmap::get_grays (  )  const [inline]

Returns the number of gray levels.

Value #2# denotes a bilevel image.

Definition at line 562 of file GBitmap.h.

unsigned int GBitmap::get_memory_usage ( void   )  const

Returns the number of bytes allocated for this image.

Definition at line 423 of file GBitmap.cpp.

const unsigned char * GBitmap::get_rle ( unsigned int &  rle_length  ) 

Return a pointer to the rle data.

Definition at line 382 of file GBitmap.cpp.

void GBitmap::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.

Definition at line 291 of file GBitmap.cpp.

void GBitmap::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.

Definition at line 247 of file GBitmap.cpp.

void GBitmap::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.

Definition at line 227 of file GBitmap.cpp.

void GBitmap::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#.

Definition at line 206 of file GBitmap.cpp.

void GBitmap::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.

Definition at line 435 of file GBitmap.cpp.

GMonitor * GBitmap::monitor (  )  const [inline]

Returns a possibly null pointer to a {GMonitor} for this bitmap.

You should use this monitor to ensure that the data representation of the bitmap will not change while you are using it. We suggest using class {GMonitorLock} which properly handles null monitor pointers.

Definition at line 603 of file GBitmap.h.

GBitmap & GBitmap::operator= ( const GBitmap &  ref  )  [inline]

Assignment operator.

Initializes this GBitmap by copying the size, the border and the contents of GBitmap ref#.

Definition at line 596 of file GBitmap.h.

unsigned char * GBitmap::operator[] ( int  row  )  [inline]

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.

Definition at line 568 of file GBitmap.h.

const unsigned char * GBitmap::operator[] ( int  row  )  const [inline]

Returns a constant pointer to the first byte of row row#.

This pointer can be used as an array to read the row elements.

Definition at line 582 of file GBitmap.h.

int GBitmap::read_run ( unsigned char *&  data  )  [inline, static]

Definition at line 622 of file GBitmap.h.

int GBitmap::read_run ( const unsigned char *&  data  )  [inline, static]

Static function for parsing run data.

This function returns one run length encoded at position data# and increments the pointer data# accordingly.

Definition at line 630 of file GBitmap.h.

void GBitmap::rle_get_bitmap ( const int  ncolumns,
const unsigned char *&  runs,
unsigned char *  bitmap,
const bool  invert 
) [static]

Gets the bitmap line rle data passed.

One line of pixel is stored one with 8 bits per unsigned char# in an array. The array must be large enough to hold the whole line.

Definition at line 1032 of file GBitmap.cpp.

int GBitmap::rle_get_bits ( int  rowno,
unsigned char *  bits 
) const

Gets the pixels for line rowno#.

One line of pixel is stored as unsigned char# values into array bits#. Each pixel is either 1 or 0. The array must be large enough to hold the whole line. The number of pixels is returned.

Definition at line 1083 of file GBitmap.cpp.

int GBitmap::rle_get_rect ( GRect &  rect  )  const

Gets the smallest rectangle enclosing black pixels.

Rectangle rect gives the coordinates of the smallest rectangle containing all black pixels. Returns the number of black pixels.

Definition at line 1148 of file GBitmap.cpp.

int GBitmap::rle_get_runs ( int  rowno,
int *  rlens 
) const

Gets the lengths of all runs in line rowno#.

The array rlens# must be large enough to accomodate w+2# integers where w# is the number of columns in the image. These integers represent the lengths of consecutive runs of alternatively white or black pixels. Lengths can be zero in order to allow for lines starting with black pixels. This function returns the total number of runs in the line.

Definition at line 1113 of file GBitmap.cpp.

GP< GBitmap > GBitmap::rotate ( int  count = 0  ) 

Rotates bitmap by 90, 180 or 270 degrees anticlockwise and returns a new pixmap, input bitmap is not changed.

count can be 1, 2, or 3 for 90, 180, 270 degree rotation. It returns the same bitmap if not rotated. The input bitmap will be uncompressed for rotation

Definition at line 1557 of file GBitmap.cpp.

unsigned int GBitmap::rows (  )  const [inline]

Returns the number of rows (the image height).

Definition at line 544 of file GBitmap.h.

unsigned int GBitmap::rowsize (  )  const [inline]

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.

Definition at line 556 of file GBitmap.h.

void GBitmap::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}.

Definition at line 890 of file GBitmap.cpp.

void GBitmap::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}.

Definition at line 943 of file GBitmap.cpp.

void GBitmap::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}.

Definition at line 985 of file GBitmap.cpp.

void GBitmap::set_grays ( int  grays  ) 

Sets the number of gray levels without changing the pixels.

Argument grays# must be in range #2# to #256#.

Definition at line 474 of file GBitmap.cpp.

void GBitmap::share (  ) 

Associates a {GMonitor} with this bitmap.

This function should be called on all bitmaps susceptible of being simultaneously used by several threads. It will make sure that function {monitor} returns a pointer to a suitable monitor for this bitmap.

Definition at line 461 of file GBitmap.cpp.

unsigned char * GBitmap::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.

Definition at line 372 of file GBitmap.cpp.

void GBitmap::uncompress (  ) 

Decodes run-length encoded bitmaps and recreate the pixel array.

This function is usually called by operator[]# when needed.

Definition at line 413 of file GBitmap.cpp.


Member Data Documentation

unsigned short GBitmap::border [protected]

Definition at line 458 of file GBitmap.h.

unsigned char* GBitmap::bytes [protected]

Definition at line 461 of file GBitmap.h.

unsigned char* GBitmap::bytes_data [protected]

Definition at line 462 of file GBitmap.h.

unsigned short GBitmap::bytes_per_row [protected]

Definition at line 459 of file GBitmap.h.

GPBuffer<unsigned char> GBitmap::gbytes_data [protected]

Definition at line 463 of file GBitmap.h.

unsigned short GBitmap::grays [protected]

Definition at line 460 of file GBitmap.h.

GPBuffer<unsigned char> GBitmap::grle [protected]

Definition at line 465 of file GBitmap.h.

GPBuffer<unsigned char *> GBitmap::grlerows [protected]

Definition at line 467 of file GBitmap.h.

GP<ZeroBuffer> GBitmap::gzerobuffer

Definition at line 474 of file GBitmap.h.

unsigned short GBitmap::ncolumns [protected]

Definition at line 457 of file GBitmap.h.

unsigned short GBitmap::nrows [protected]

Definition at line 456 of file GBitmap.h.

unsigned char* GBitmap::rle [protected]

Definition at line 464 of file GBitmap.h.

unsigned int GBitmap::rlelength [protected]

Definition at line 468 of file GBitmap.h.

unsigned char** GBitmap::rlerows [protected]

Definition at line 466 of file GBitmap.h.


The documentation for this class was generated from the following files:
  • GBitmap.h
  • GBitmap.cpp

kviewshell

Skip menu "kviewshell"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members

API Reference

Skip menu "API Reference"
  • kviewshell
Generated for API Reference by doxygen 1.5.9
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal