Dragengine.Gui.EditableImage Class Reference

Editable image. More...

Inheritance diagram for Dragengine.Gui.EditableImage:

Public Member Functions
Constructors
EditableImage	new (int width, int height, int depth, int componentCount, int bitCount)
	Create EditableImage instance to access pixel data. More...
Management
Image	getImage ()
	Image resource. More...
int	getWidth ()
	Width in pixels. More...
int	getHeight ()
	Height in pixels. More...
int	getDepth ()
	Depth in layers. More...
Color	getAt (int x, int y)
	Color of pixel at coordinate. More...
Color	getAt (int x, int y, int z)
	Color of pixel at coordinate. More...
void	getRange (Array pixels, int x, int y, int width, int height)
	Range of pixels. More...
void	getRange (Array pixels, int x, int y, int z, int width, int height, int depth)
	Range of pixels. More...
void	clear (Color color)
	Clear image to color. More...
void	setAt (int x, int y, Color color)
	Set color of pixel at coordinate. More...
void	setAt (int x, int y, int z, Color color)
	Set color of pixel at coordinate. More...
void	setRange (int x, int y, int width, int height, Array pixels)
	Set range of pixels. More...
void	setRange (int x, int y, int z, int width, int height, int depth, Array pixels)
	Set range of pixels. More...
void	contentChanged ()
	Notify module content of image changed. More...

Detailed Description

Editable image.

Allows modifying pixels in an image.

Image resources can consume a lot of CPU memory. This amount of memory is usually wasted since Graphic Modules tend to process and store the image data in GPU resources. Once stored the original image data is not required to be present in CPU memory and will be released.

This class creates an in-memory image resouce with retained image data to allow modifying pixels data from script classes. Once the instance is destroyed the retained data is released.

The image resource contained inside an editable image can be used like an image resource loaded from file with the exception that once you change the image pixels you have to call contentChanged() to make Graphic Module update GPU side resources. Without calling contentChanged() the old content typically stays visible.

A typical use case for editable images are dynamic height terrains. For this create an EditableImage with 1 component count and 32 bit count and assign the image as height terrain height image. You can now change the heights of individual pixels and call contentChanged() to make the changes visible.

Another use case is creating dynamic images you have to modify pixel precise. Usually using CanvasView and capturing the image inside is the better solution but if many updates on pixel basis are done an EditableImage is the better choice.

Pixels retrieved from the image are converted to full colors like this:

• 1 component: Color.new( value, value, value, 1 )
• 2 components: Color.new( value, value, value, alpha )
• 3 components: Color.new( red, green, blue, 1 )
• 4 components: Color.new( red, green, blue, alpha )

Pixels assigned to the image are converted from full colors like this:

• 1 component: color.getRed()
• 2 components: color.getRed(), color.getAlpha()
• 3 components: color.getRed(), color.getGreen(), color.getBlue()
• 4 components: color.getRed(), color.getGreen(), color.getBlue(), color.getAlpha()

This is a native class.

Member Function Documentation

clear()

void Dragengine.Gui.EditableImage.clear

(

Color

color

)

Clear image to color.

contentChanged()

void Dragengine.Gui.EditableImage.contentChanged

(

)

Notify module content of image changed.

Always call this method after changing pixels.

getAt() [1/2]

Color Dragengine.Gui.EditableImage.getAt	(	int	x,
		int	y
	)

Color of pixel at coordinate.

Exceptions

EInvalidParam	x < 0.
EInvalidParam	x >= image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	y >= image.getHeight().

getAt() [2/2]

Color Dragengine.Gui.EditableImage.getAt	(	int	x,
		int	y,
		int	z
	)

Color of pixel at coordinate.

Exceptions

EInvalidParam	x < 0.
EInvalidParam	x >= image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	y >= image.getHeight().
EInvalidParam	z < 0.
EInvalidParam	z >= image.getDepth().

getDepth()

int Dragengine.Gui.EditableImage.getDepth

(

)

Depth in layers.

getHeight()

int Dragengine.Gui.EditableImage.getHeight

(

)

Height in pixels.

getImage()

Image Dragengine.Gui.EditableImage.getImage

(

)

Image resource.

getRange() [1/2]

void Dragengine.Gui.EditableImage.getRange	(	Array	pixels,
		int	x,
		int	y,
		int	width,
		int	height
	)

Range of pixels.

pixels is required to be of size "width * height". Content of pixels will be replaced with Color instances of the pixels in the desired range. The index of each pixel is "height * y + x".

Exceptions

ENullPointer	pixels is null.
EInvalidParam	x < 0.
EInvalidParam	width < 0.
EInvalidParam	x + width > image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	height < 0.
EInvalidParam	y + height > image.getHeight().
EInvalidParam	pixels.getCount != width * height.

getRange() [2/2]

void Dragengine.Gui.EditableImage.getRange	(	Array	pixels,
		int	x,
		int	y,
		int	z,
		int	width,
		int	height,
		int	depth
	)

Range of pixels.

pixels is required to be of size "width * height * depth". Content of pixels will be replaced with Color instances of the pixels in the desired range. The index of each pixel is "width * height * z + height * y + x".

Exceptions

ENullPointer	pixels is null.
EInvalidParam	x < 0.
EInvalidParam	width < 0.
EInvalidParam	x + width > image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	height < 0.
EInvalidParam	y + height > image.getHeight().
EInvalidParam	z < 0.
EInvalidParam	depth < 0.
EInvalidParam	z + depth > image.getDepth().
EInvalidParam	pixels.getCount != width * height * depth.

getWidth()

int Dragengine.Gui.EditableImage.getWidth

(

)

Width in pixels.

new()

EditableImage Dragengine.Gui.EditableImage.new	(	int	width,
		int	height,
		int	depth,
		int	componentCount,
		int	bitCount
	)

Create EditableImage instance to access pixel data.

Potentially causes loading image data into memory. Upon destruction image data is released from memory.

setAt() [1/2]

void Dragengine.Gui.EditableImage.setAt	(	int	x,
		int	y,
		Color	color
	)

Set color of pixel at coordinate.

Exceptions

EInvalidParam	x < 0.
EInvalidParam	x >= image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	y >= image.getHeight().

setAt() [2/2]

void Dragengine.Gui.EditableImage.setAt	(	int	x,
		int	y,
		int	z,
		Color	color
	)

Set color of pixel at coordinate.

Exceptions

EInvalidParam	x < 0.
EInvalidParam	x >= image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	y >= image.getHeight().
EInvalidParam	z < 0.
EInvalidParam	z >= image.getDepth().

setRange() [1/2]

void Dragengine.Gui.EditableImage.setRange	(	int	x,
		int	y,
		int	width,
		int	height,
		Array	pixels
	)

Set range of pixels.

pixels is required to be of size "width * height". Content of pixels has to be instances of Color of the pixels in the desired range. The index of each pixel is "height * y + x".

Exceptions

ENullPointer	pixels is null.
EInvalidCast	element in pixels is not of type Color.
EInvalidParam	x < 0.
EInvalidParam	width < 0.
EInvalidParam	x + width > image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	height < 0.
EInvalidParam	y + height > image.getHeight().
EInvalidParam	pixels.getCount != width * height.

setRange() [2/2]

void Dragengine.Gui.EditableImage.setRange	(	int	x,
		int	y,
		int	z,
		int	width,
		int	height,
		int	depth,
		Array	pixels
	)

Set range of pixels.

pixels is required to be of size "width * height * depth". Content of pixels has to be instance of Color of the pixels in the desired range. The index of each pixel is "width * height * z + height * y + x".

Exceptions

ENullPointer	pixels is null.
EInvalidCast	element in pixels is not of type Color.
EInvalidParam	x < 0.
EInvalidParam	width < 0.
EInvalidParam	x + width > image.getWidth().
EInvalidParam	y < 0.
EInvalidParam	height < 0.
EInvalidParam	y + height > image.getHeight().
EInvalidParam	z < 0.
EInvalidParam	depth < 0.
EInvalidParam	z + depth > image.getDepth().
EInvalidParam	pixels.getCount != width * height * depth.

---

The documentation for this class was generated from the following file:

• EditableImage.ds