Bitmap¶

The Bitmap class holds an image.

Unlike Layer, it is not a display element, so it can be created on its own, independent of any window or layer tree, and drawing to it does not trigger redraw notifications. Use it for off-screen working images and for holding assets.

Bitmap itself has no drawing methods. To composite, fill, draw text, apply filters and so on, pass the Bitmap object to methods of the ImageFunction class.

To exchange images with a Layer, use Layer.copyToBitmapFromMainImage / Layer.copyFromBitmapToMainImage. In addition, a Bitmap can be passed directly as the source (operand) of Layer's copyRect / operateRect / stretchCopy / operateStretch / affineCopy / operateAffine / copy9Patch.

For how the three relate and when to use which, see Layer, Bitmap and ImageFunction.

Members¶

Bitmap¶

Constructor

Description

Constructs a Bitmap object

Constructs an object of the Bitmap class.

Initially, the width and height are 32 pixels.

Bitmap¶

Constructor

Arguments

Arguments	Default	Description
`width`	` `	Image width.
`height`	` `	Image height.
`bpp`	`32`	Number of bits per pixel. Specify either 32 or 8.

Description

Constructs a Bitmap object

Constructs an object of the Bitmap class with the given size.

Bitmap¶

Constructor

Arguments

Arguments	Default	Description
`filename`	` `	Image file name.
`colorkey`	`clNone`	Color key. The values are the same as for Layer.loadImages.

Description

Constructs a Bitmap object

Constructs an object of the Bitmap class from a file.

width¶

Property \ Access: r/w

Description

Image width

Image width in pixels.

This property can also be set.

See also: Bitmap.setSize

height¶

Property \ Access: r/w

Description

Image height

Image height in pixels.

This property can also be set.

See also: Bitmap.setSize

buffer¶

Property \ Access: r

Description

Image buffer pointer

Pointer to the top-left corner of the image buffer (a 32bpp bitmap containing color and mask (opacity) information).

This property provides direct access to the image buffer for plugins and the like.

It is returned as an integer; in a plugin, cast it to an appropriate type (const unsigned long * etc.) before use.

Do not write to the pointer obtained from this property. You can write to the pointer obtained from Bitmap.bufferForWrite.

The image size is given by the Bitmap.width and Bitmap.height properties.

For how to compute pointers, see Bitmap.bufferPitch.

See also: Bitmap.bufferForWrite / Bitmap.bufferPitch

bufferForWrite¶

Property \ Access: r

Description

Image buffer pointer (for writing)

Pointer to the top-left corner of the image buffer (a 32bpp bitmap containing color and mask (opacity) information).

This property provides direct access to the image buffer for plugins and the like.

It is returned as an integer; in a plugin, cast it to an appropriate type (unsigned long * etc.) before use.

Unlike Bitmap.buffer, you can write to the pointer obtained from this property. Internally, Kirikiri shares identical images among multiple objects; reading this property breaks that sharing.

The image size is given by the Bitmap.width and Bitmap.height properties.

For how to compute pointers, see Bitmap.bufferPitch.

See also: Bitmap.buffer / Bitmap.bufferPitch

bufferPitch¶

Property \ Access: r

Description

Image buffer pitch

Pitch of the image buffer (a 32bpp bitmap containing color and mask (opacity) information), i.e. the number of bytes to the next scan line down.

This property provides direct access to the image buffer for plugins and the like.

With tjs_uint32 as a 32-bit integer type and tjs_uint8 as an 8-bit (1-byte) integer type, the pointer to image position (x, y) can be computed in C as follows.

( (tjs_uint32*)( (tjs_uint8*)buffer + y*bufferPitch )) + x

Note that this property returns the number of bytes to the next scan line, not the number of pixels. The value may be somewhat larger than the number of bytes strictly required for the image width.

Note that this value can be negative.

See also: Bitmap.buffer / Bitmap.bufferForWrite

loading¶

Property \ Access: r

Description

Whether asynchronous loading is in progress

Indicates whether asynchronous loading is in progress.

While this is true, asynchronous loading is in progress.

Note that accessing other members during asynchronous loading throws an exception.

See also: Bitmap.buffer / Bitmap.bufferPitch

imageWidth¶

Property \ Access: r

Description

Image width (alias of Bitmap.width)

Image width in pixels. A read-only alias that returns the same value as Bitmap.width.

It exists so that draw devices and plugins can get the image through a property of the same name without distinguishing between Layer and Bitmap (same name as Layer.imageWidth).

See also: Bitmap.width / Bitmap.imageHeight

imageHeight¶

Property \ Access: r

Description

Image height (alias of Bitmap.height)

Image height in pixels. A read-only alias that returns the same value as Bitmap.height.

It exists so that draw devices and plugins can get the image through a property of the same name without distinguishing between Layer and Bitmap (same name as Layer.imageHeight).

See also: Bitmap.height / Bitmap.imageWidth

mainImageBuffer¶

Property \ Access: r

Description

Image buffer pointer (alias of Bitmap.buffer)

Pointer to the top-left corner of the image buffer. A read-only alias that returns the same value as Bitmap.buffer.

It exists so that draw devices and plugins can get the image through a property of the same name without distinguishing between Layer and Bitmap (same name as Layer.mainImageBuffer). Do not write to this pointer; to write, use Bitmap.mainImageBufferForWrite.

mainImageBufferForWrite¶

Property \ Access: r

Description

Image buffer pointer for writing (alias of Bitmap.bufferForWrite)

Pointer to the top-left corner of the writable image buffer. A read-only alias that returns the same value as Bitmap.bufferForWrite (reading it breaks image sharing).

It exists so that draw devices and plugins can get the image through a property of the same name without distinguishing between Layer and Bitmap (same name as Layer.mainImageBufferForWrite).

mainImageBufferPitch¶

Property \ Access: r

Description

Image buffer pitch (alias of Bitmap.bufferPitch)

Pitch of the image buffer (the number of bytes to the next scan line down). A read-only alias that returns the same value as Bitmap.bufferPitch (the value can be negative).

It exists so that draw devices and plugins can get the image through a property of the same name without distinguishing between Layer and Bitmap (same name as Layer.mainImageBufferPitch).

getPixel¶

Method

Arguments

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Return value

Pixel value

Description

Gets a pixel value

Gets a pixel value of the image.

See also: Bitmap.setPixel

setPixel¶

Method

Arguments

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Pixel value to set.

Description

Sets a pixel value

Sets a pixel value of the image.

See also: Bitmap.getPixel

getMaskPixel¶

Method

Arguments

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Return value

Alpha value of the pixel

Description

Gets the alpha value of a pixel

Gets the alpha value of a pixel of the image.

See also: Bitmap.setMaskPixel

setMaskPixel¶

Method

Arguments

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Alpha value of the pixel to set.

Description

Sets the alpha value of a pixel

Sets the alpha value of a pixel of the image.

See also: Bitmap.getMaskPixel

independ¶

Method

Arguments

Arguments	Default	Description
`copy`	`true`	Whether to copy the original image when breaking the sharing. If true, the original image is copied. If false, it is not copied and the image contents are undefined.

Description

Stops sharing the image

Forces the image out of the shared state.

When you copy a whole image, e.g. with assignImages, Kirikiri does not actually copy the image buffer; the objects share the same image instead.

Normally the sharing is broken automatically just before the image is modified, but this method lets you break it explicitly.

If you pass false for the copy argument, the sharing is broken but the original image is not guaranteed to be carried over (the image contents become undefined); in exchange, breaking the sharing is faster. If you are going to rewrite the whole image you do not need the original, so calling this method with false before drawing may be more efficient.

This method does nothing if the image is not shared.

setSize¶

Method

Arguments

Arguments	Default	Description
`width`	` `	Image width in pixels. This value can also be read and written via the Bitmap.width property.
`height`	` `	Image height in pixels. This value can also be read and written via the Bitmap.height property.

Description

Sets the image size

Sets the image size.

copyFrom¶

Method

Arguments

Arguments	Default	Description
`src`	` `	Source Bitmap object.

Description

Copies an image

Copies an image.

The "copy" merely makes two or more objects share the same image, so this method takes almost no time.

save¶

Method

Arguments

Arguments	Default	Description
`name`	` `	Name of the storage to save to.
`type`	`"bmp"`	Image format to save in, as a string. The current version supports the following formats. "bmp" or "bmp32" 32bpp BMP. The alpha channel (mask) is saved too. "bmp24" 24bpp BMP. The alpha channel (mask) is not saved. "bmp8" 8bpp BMP. The alpha channel (mask) is not saved. The image is color-reduced with 4x4 ordered dithering to a fixed 252-color palette. "jpg" JPEG. The alpha channel (mask) is not saved. The image is saved at 90% quality. "jpg###" JPEG. The alpha channel (mask) is not saved. The image is saved at the quality given by ###: "jpg010" is 10%, "jpg100" is 100%, "jpg080" is 80%. "png" 32bpp PNG. The alpha channel (mask) is saved too. "png24" 24bpp PNG. The alpha channel (mask) is not saved. "tlg5" 32bpp TLG5. The alpha channel (mask) is saved too. "tlg524" 24bpp TLG5. The alpha channel (mask) is not saved. "tlg6" 32bpp TLG6. The alpha channel (mask) is saved too. "tlg624" 24bpp TLG6. The alpha channel (mask) is not saved.
`meta`	`null`	For TLG formats, the tag information to save, as a dictionary. For other formats, additional options (1.3.0 and later). The available options can be obtained with getSaveOption.

Description

Saves the image

Saves the image to the storage (file) specified by name, in the image format specified by type.

See also: Bitmap.getSaveOption

load¶

Method

Arguments

Arguments	Default	Description
`image`	` `	Image storage to load.
`colorkey`	`clNone`	Color key (transparent color) of the image to load. If you specify a color in 0xRRGGBB format, that color becomes the color key. If you specify `clPalIdx` plus a palette index, that palette index becomes transparent (for images with 256 colors or fewer). If you specify `clAdapt`, the color used most often in the top line of the image automatically becomes transparent. If you specify `clAlphaMat` plus a color in 0xRRGGBB format, the image is composited onto that color using alpha blending (the ltAlpha method). For example, specifying (clAlphaMat + 0xffffff) composites the loaded image onto white. The resulting image is fully opaque (note that although the image becomes fully opaque, this mode does not change the tag information at all).

Return value

Dictionary of tag information

Description

Loads an image

Loads an image.

Returns a dictionary of tag information (information about the image itself, such as its layer type and display position).

If the image has no tag information, null is returned.

In the current version, only PNG and TLG5/6 images can carry tag information. For the information available, see Image Format Converter.

loadAsync¶

Method

Arguments

Arguments	Default	Description
`image`	` `	Image storage to load. Note that the file name must include the extension. Without an extension the file is not found and an error occurs.

Description

Loads an image asynchronously

Loads an image asynchronously.

Completion is reported via Bitmap.onLoaded.

You can check whether asynchronous loading is in progress with Bitmap.loading.

While asynchronous loading is in progress, accessing any member other than Bitmap.loading throws an exception.

See also the description of Bitmap.onLoaded.

loadHeader¶

Method

Arguments

Arguments	Default	Description
`image`	` `	Image storage to load. Note that the file name must include the extension. Without an extension the file is not found and an error occurs.

Return value

Dictionary of information

Description

Loads image information (1.3.0 and later)

Loads only the image information.

The image itself is not loaded, so this is fast when you only need the information.

The returned dictionary always contains width and height; other information depends on the image format.

getSaveOption¶

Method

Arguments

Arguments	Default	Description
`type`	` `	Image format. Specified in the same form as for the save method.

Return value

Dictionary of additional information

Description

Gets additional save options (1.3.0 and later)

Gets the additional information that can be specified when saving an image.

See also: Bitmap.save

onLoaded¶

Event

Arguments

Arguments	Default	Description
`meta`	` `	Tag information of the loaded image.
`async`	` `	Whether the image was loaded asynchronously. If the image data is in the cache, this event fires while Bitmap.loadAsync is still executing.
`error`	` `	Whether an error occurred while loading the image.
`message`	` `	Error message. If an error occurred, the error message is passed here.

Description

Asynchronous loading has completed

Fired when asynchronous loading completes.

The loaded image can be copied to a Layer with Layer.copyFromBitmapToMainImage.

Because loading is asynchronous, the Layer you intend to pass the image to may already have been invalidated when loading completes.

If you access other objects in this event, check that they have not been invalidated.

Alternatively, make sure the target objects are not invalidated until this event completes.

Arguments	Default	Description
`width`	` `	Image width.
`height`	` `	Image height.
`bpp`	`32`	Number of bits per pixel. Specify either 32 or 8.

Arguments	Default	Description
`filename`	` `	Image file name.
`colorkey`	`clNone`	Color key. The values are the same as for Layer.loadImages.

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Pixel value to set.

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Alpha value of the pixel to set.

Arguments	Default	Description
`width`	` `	Image width in pixels. This value can also be read and written via the Bitmap.width property.
`height`	` `	Image height in pixels. This value can also be read and written via the Bitmap.height property.

Arguments	Default	Description
`name`	` `	Name of the storage to save to.
`type`	`"bmp"`	Image format to save in, as a string. The current version supports the following formats. "bmp" or "bmp32" 32bpp BMP. The alpha channel (mask) is saved too. "bmp24" 24bpp BMP. The alpha channel (mask) is not saved. "bmp8" 8bpp BMP. The alpha channel (mask) is not saved. The image is color-reduced with 4x4 ordered dithering to a fixed 252-color palette. "jpg" JPEG. The alpha channel (mask) is not saved. The image is saved at 90% quality. "jpg###" JPEG. The alpha channel (mask) is not saved. The image is saved at the quality given by ###: "jpg010" is 10%, "jpg100" is 100%, "jpg080" is 80%. "png" 32bpp PNG. The alpha channel (mask) is saved too. "png24" 24bpp PNG. The alpha channel (mask) is not saved. "tlg5" 32bpp TLG5. The alpha channel (mask) is saved too. "tlg524" 24bpp TLG5. The alpha channel (mask) is not saved. "tlg6" 32bpp TLG6. The alpha channel (mask) is saved too. "tlg624" 24bpp TLG6. The alpha channel (mask) is not saved.
`meta`	`null`	For TLG formats, the tag information to save, as a dictionary. For other formats, additional options (1.3.0 and later). The available options can be obtained with getSaveOption.

Arguments	Default	Description
`image`	` `	Image storage to load.
`colorkey`	`clNone`	Color key (transparent color) of the image to load. If you specify a color in 0xRRGGBB format, that color becomes the color key. If you specify `clPalIdx` plus a palette index, that palette index becomes transparent (for images with 256 colors or fewer). If you specify `clAdapt`, the color used most often in the top line of the image automatically becomes transparent. If you specify `clAlphaMat` plus a color in 0xRRGGBB format, the image is composited onto that color using alpha blending (the ltAlpha method). For example, specifying (clAlphaMat + 0xffffff) composites the loaded image onto white. The resulting image is fully opaque (note that although the image becomes fully opaque, this mode does not change the tag information at all).

Arguments	Default	Description
`meta`	` `	Tag information of the loaded image.
`async`	` `	Whether the image was loaded asynchronously. If the image data is in the cache, this event fires while Bitmap.loadAsync is still executing.
`error`	` `	Whether an error occurred while loading the image.
`message`	` `	Error message. If an error occurred, the error message is passed here.

Arguments	Default	Description
`width`	` `	Image width.
`height`	` `	Image height.
`bpp`	`32`	Number of bits per pixel. Specify either 32 or 8.

Arguments	Default	Description
`filename`	` `	Image file name.
`colorkey`	`clNone`	Color key. The values are the same as for Layer.loadImages.

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Pixel value to set.

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Alpha value of the pixel to set.

Arguments	Default	Description
`width`	` `	Image width in pixels. This value can also be read and written via the Bitmap.width property.
`height`	` `	Image height in pixels. This value can also be read and written via the Bitmap.height property.

Arguments	Default	Description
`name`	` `	Name of the storage to save to.
`type`	`"bmp"`	Image format to save in, as a string. The current version supports the following formats. "bmp" or "bmp32" 32bpp BMP. The alpha channel (mask) is saved too. "bmp24" 24bpp BMP. The alpha channel (mask) is not saved. "bmp8" 8bpp BMP. The alpha channel (mask) is not saved. The image is color-reduced with 4x4 ordered dithering to a fixed 252-color palette. "jpg" JPEG. The alpha channel (mask) is not saved. The image is saved at 90% quality. "jpg###" JPEG. The alpha channel (mask) is not saved. The image is saved at the quality given by ###: "jpg010" is 10%, "jpg100" is 100%, "jpg080" is 80%. "png" 32bpp PNG. The alpha channel (mask) is saved too. "png24" 24bpp PNG. The alpha channel (mask) is not saved. "tlg5" 32bpp TLG5. The alpha channel (mask) is saved too. "tlg524" 24bpp TLG5. The alpha channel (mask) is not saved. "tlg6" 32bpp TLG6. The alpha channel (mask) is saved too. "tlg624" 24bpp TLG6. The alpha channel (mask) is not saved.
`meta`	`null`	For TLG formats, the tag information to save, as a dictionary. For other formats, additional options (1.3.0 and later). The available options can be obtained with getSaveOption.

Arguments	Default	Description
`image`	` `	Image storage to load.
`colorkey`	`clNone`	Color key (transparent color) of the image to load. If you specify a color in 0xRRGGBB format, that color becomes the color key. If you specify `clPalIdx` plus a palette index, that palette index becomes transparent (for images with 256 colors or fewer). If you specify `clAdapt`, the color used most often in the top line of the image automatically becomes transparent. If you specify `clAlphaMat` plus a color in 0xRRGGBB format, the image is composited onto that color using alpha blending (the ltAlpha method). For example, specifying (clAlphaMat + 0xffffff) composites the loaded image onto white. The resulting image is fully opaque (note that although the image becomes fully opaque, this mode does not change the tag information at all).

Arguments	Default	Description
`meta`	` `	Tag information of the loaded image.
`async`	` `	Whether the image was loaded asynchronously. If the image data is in the cache, this event fires while Bitmap.loadAsync is still executing.
`error`	` `	Whether an error occurred while loading the image.
`message`	` `	Error message. If an error occurred, the error message is passed here.

Bitmap¶

Members¶

Constructors¶

Properties¶

Methods¶

Events¶

Bitmap¶

Bitmap¶

Bitmap¶

width¶

height¶

buffer¶

bufferForWrite¶

bufferPitch¶

loading¶

imageWidth¶

imageHeight¶

mainImageBuffer¶

mainImageBufferForWrite¶

mainImageBufferPitch¶

getPixel¶

setPixel¶

getMaskPixel¶

setMaskPixel¶

independ¶

setSize¶

copyFrom¶

save¶

load¶

loadAsync¶

loadHeader¶

getSaveOption¶

onLoaded¶

Arguments	Default	Description
`width`	` `	Image width.
`height`	` `	Image height.
`bpp`	`32`	Number of bits per pixel. Specify either 32 or 8.

Arguments	Default	Description
`filename`	` `	Image file name.
`colorkey`	`clNone`	Color key. The values are the same as for Layer.loadImages.

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Pixel value to set.

Arguments	Default	Description
`x`	` `	x coordinate to read, in pixels.
`y`	` `	y coordinate to read, in pixels.

Arguments	Default	Description
`x`	` `	x coordinate to write, in pixels.
`y`	` `	y coordinate to write, in pixels.
`value`	` `	Alpha value of the pixel to set.

Arguments	Default	Description
`width`	` `	Image width in pixels. This value can also be read and written via the Bitmap.width property.
`height`	` `	Image height in pixels. This value can also be read and written via the Bitmap.height property.

Arguments	Default	Description
`name`	` `	Name of the storage to save to.
`type`	`"bmp"`	Image format to save in, as a string. The current version supports the following formats. "bmp" or "bmp32" 32bpp BMP. The alpha channel (mask) is saved too. "bmp24" 24bpp BMP. The alpha channel (mask) is not saved. "bmp8" 8bpp BMP. The alpha channel (mask) is not saved. The image is color-reduced with 4x4 ordered dithering to a fixed 252-color palette. "jpg" JPEG. The alpha channel (mask) is not saved. The image is saved at 90% quality. "jpg###" JPEG. The alpha channel (mask) is not saved. The image is saved at the quality given by ###: "jpg010" is 10%, "jpg100" is 100%, "jpg080" is 80%. "png" 32bpp PNG. The alpha channel (mask) is saved too. "png24" 24bpp PNG. The alpha channel (mask) is not saved. "tlg5" 32bpp TLG5. The alpha channel (mask) is saved too. "tlg524" 24bpp TLG5. The alpha channel (mask) is not saved. "tlg6" 32bpp TLG6. The alpha channel (mask) is saved too. "tlg624" 24bpp TLG6. The alpha channel (mask) is not saved.
`meta`	`null`	For TLG formats, the tag information to save, as a dictionary. For other formats, additional options (1.3.0 and later). The available options can be obtained with getSaveOption.

Arguments	Default	Description
`image`	` `	Image storage to load.
`colorkey`	`clNone`	Color key (transparent color) of the image to load. If you specify a color in 0xRRGGBB format, that color becomes the color key. If you specify `clPalIdx` plus a palette index, that palette index becomes transparent (for images with 256 colors or fewer). If you specify `clAdapt`, the color used most often in the top line of the image automatically becomes transparent. If you specify `clAlphaMat` plus a color in 0xRRGGBB format, the image is composited onto that color using alpha blending (the ltAlpha method). For example, specifying (clAlphaMat + 0xffffff) composites the loaded image onto white. The resulting image is fully opaque (note that although the image becomes fully opaque, this mode does not change the tag information at all).

Arguments	Default	Description
`meta`	` `	Tag information of the loaded image.
`async`	` `	Whether the image was loaded asynchronously. If the image data is in the cache, this event fires while Bitmap.loadAsync is still executing.
`error`	` `	Whether an error occurred while loading the image.
`message`	` `	Error message. If an error occurred, the error message is passed here.