bhlib/doc/Manual/en/BH_Bitmap.pod

=encoding UTF-8


=head1 NAME

BH_Bitmap - bitmap/image access


=head1 SYNTAX

 #include <BH/Bitmap.h>

 cc prog.c -o prog -lbh


=head1 DESCRIPTION

The BH_Bitmap module provides methods for accessing the pixel data of a bitmap
(image) and for converting between different pixel formats.


=head1 FORMATS

Currently, the following pixel formats are supported:

=over

=item B<BH_BITMAP_INDEX1>

1-bit indexed/paletted (bits are packed with most significant bit first)

=item B<BH_BITMAP_INDEX1_LSB>

1-bit index/paletted with (bits are packed with least significant bit first)

=item B<BH_BITMAP_INDEX2>

2-bit indexed/paletted (bits are packed with most significant bit first)

=item B<BH_BITMAP_INDEX2_LSB>

2-bit indexed/paletted (bits are packed with least significant bit first)

=item B<BH_BITMAP_INDEX4>

4-bit indexed/paletted (bits are packed with most significant bit first)

=item B<BH_BITMAP_INDEX4_LSB>

4-bit indexed/paletted (bits are packed with least significant bit first)

=item B<BH_BITMAP_INDEX8>

8-bit indexed/paletted

=item B<BH_BITMAP_GRAY8>

8-bit grayscale

=item B<BH_BITMAP_GRAY16>

16-bit grayscale

=item B<BH_BITMAP_RGBA32>

32-bit RGB with alpha represented in uint32_t value. The layout is: 0xAARRGGBB

=item B<BH_BITMAP_RGBA64>

64-bit RGB with alpha represented in uint64_t value. The layout is:
0xAAAARRRRGGGGBBBB

=item B<BH_BITMAP_RGBA5551>, B<BH_BITMAP_BGRA5551>, B<BH_BITMAP_ARGB1555>, B<BH_BITMAP_ABGR1555>

16-bit RGB

=item B<BH_BITMAP_RGB565>, B<BH_BITMAP_BGR565>

16-bit RGB

=item B<BH_BITMAP_RGB888>, B<BH_BITMAP_BGR888>

24-bit RGB

=item B<BH_BITMAP_RGBA8888>, B<BH_BITMAP_BGRA8888>, B<BH_BITMAP_ARGB8888>, B<BH_BITMAP_ABGR8888>

32-bit RGB with alpha

=item B<BH_BITMAP_RGB161616>, B<BH_BITMAP_BGR161616>

48-bit RGB

=item B<BH_BITMAP_RGBA16161616>, B<BH_BITMAP_BGRA16161616>, B<BH_BITMAP_ARGB16161616>, B<BH_BITMAP_ABGR16161616>

64-bit RGB with alpha

=item B<BH_BITMAP_RGBA1010102>, B<BH_BITMAP_BGRA1010102>, B<BH_BITMAP_ARGB1010102>, B<BH_BITMAP_ABGR1010102>

32-bit RGB with alpha

=back

All pixel formats use the current machine endianness.

The flag I<BH_BITMAP_NOALPHA> can be used to indicate that the alpha channel is
not used and should always be set to the maximum value (255 for 8-bit and 65535
for 16-bit).

The flag I<BH_BITMAP_PREMULT>  can be used to indicate that color values are in
premultiplied form.


=head1 API CALLS


=head2 BH_BitmapNew

 BH_Bitmap *BH_BitmapNew(uint32_t width,
                         uint32_t height,
                         int format,
                         int flags,
                         void *data,
                         BH_Color *palette,
                         int *result);

Creates the bitmap with the specified I<width>, I<height> and pixel I<format>.

The I<flags> parameter can take a combination of the following values:

=over

=item B<BH_BITMAP_FLAG_ALIGN32>

Rows are aligned to 32-bit boundary

=back

The optional I<data> parameter specifies pointer to the existing data.

The optional I<palette> parameter specifies pointer to the existing palette.

The optional parameter I<result> returns 0 or an error code.

This function returns a pointer to a new BH_Bitmap object or NULL.


=head2 BH_BitmapFree

 void BH_BitmapFree(BH_Bitmap *bitmap);

Destroys the bitmap object.


=head2 BH_BitmapColor

 void BH_BitmapColor(const BH_Bitmap *bitmap,
                     uint32_t x,
                     uint32_t y,
                     BH_Color *value);

Reads color value of the pixel at specified position.

The I<x> and I<y> parameters specify a position on the bitmap.


=head2 BH_BitmapSetColor

 void BH_BitmapSetColor(BH_Bitmap *bitmap,
                        uint32_t x,
                        uint32_t y,
                        const BH_Color *value);

Writes color value of the pixel at specified position.

The I<x> and I<y> parameters specify a position on the bitmap.


=head2 BH_BitmapIndex

 uint8_t BH_BitmapIndex(const BH_Bitmap *bitmap,
                        uint32_t x,
                        uint32_t y);

Returns the index value at the specified position.

The I<x> and I<y> parameters specify a position on the bitmap.


=head2 BH_BitmapSetIndex

 void BH_BitmapSetIndex(BH_Bitmap *bitmap,
                        uint32_t x,
                        uint32_t y,
                        uint8_t index);

Sets the index value at the specified position.

The I<x> and I<y> parameters specify a position on the bitmap.


=head2 BH_BitmapCopy

 BH_Bitmap *BH_BitmapCopy(BH_Bitmap *bitmap,
                          uint32_t x,
                          uint32_t y,
                          uint32_t width,
                          uint32_t height,
                          int shallow,
                          int *result);

Creates a copy of the bitmap region by the given position and size.

The I<x> and I<y> parameters specify a position on the bitmap.

The I<width> and I<height> parameters specify size of the new bitmap.

The I<shallow> parameter specifies whether the new bitmap is a shallow copy (or
a view) of the existing bitmap or a deep copy. For the shallow copy to work, the
region should be within the existing bitmap.

The optional parameter I<result> returns 0 or an error code.

This function returns a pointer to a new BH_Bitmap object or NULL.


=head2 BH_BitmapScanline

 void *BH_BitmapScanline(const BH_Bitmap *bitmap,
                         uint32_t y);

Returns address of the scanline in the bitmap.


=head2 BH_BitmapAt

 void *BH_BitmapAt(const BH_Bitmap *bitmap,
                   uint32_t x,
                   uint32_t y);

Returns address of the pixel in the bitmap.


=head2 BH_BitmapWidth

 uint32_t BH_BitmapWidth(BH_Bitmap *bitmap);

Returns width of the bitmap.


=head2 BH_BitmapHeight

 uint32_t BH_BitmapHeight(BH_Bitmap *bitmap);

Returns height of the bitmap.


=head2 BH_BitmapFormat

 int BH_BitmapFormat(BH_Bitmap *bitmap);

Returns pixel format of the bitmap.


=head2 BH_BitmapStride

 size_t BH_BitmapStride(BH_Bitmap *bitmap);

Returns row stride of the bitmap.


=head2 BH_BitmapData

 void *BH_BitmapData(BH_Bitmap *bitmap);

Returns pointer to the pixel data of the bitmap.


=head2 BH_BitmapPalette

 void *BH_BitmapPalette(BH_Bitmap *bitmap);

Returns pointer to the bitmap's palette.


=head2 BH_BitmapFlags

 int BH_BitmapFlags(BH_Bitmap *bitmap);

Returns bitmap's flags.

The result can be a combination of the following values:

=over

=item B<BH_BITMAP_FLAG_ALIGN32>

Rows are aligned to 32-bit boundary

=item B<BH_BITMAP_FLAG_EXT_DATA>

Bitmap doesn't own the pixel data

=item B<BH_BITMAP_FLAG_EXT_PALETTE>

Bitmap doesn't own palette data

=back


=head2 BH_BitmapConvertRow

 void BH_BitmapConvertRow(void *src,
                          int srcFormat,
                          const BH_Color *srcPalette,
                          void *dest,
                          int destFormat,
                          const BH_Color *destPalette,
                          size_t count);

Converts a row of source data from one pixel format to another pixel format.

The parameter I<src> and I<srcFormat> specify the source of the data and its
pixel format.

The parameter I<srcPalette> specify the source palette (if required by the pixel
format).

The parameter I<dest> and I<destFormat> specify the destination of the data and
its pixel format.

The parameter I<destPalette> specify the destination palette (if required by the
pixel format).

The parameter I<count> specifies the number of pixel for conversion.


=head1 SEE ALSO

L<BH>