Drag[en]gine Script Module DragonScript  1.23
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
EInvalidParamx < 0.
EInvalidParamx >= image.getWidth().
EInvalidParamy < 0.
EInvalidParamy >= image.getHeight().

◆ getAt() [2/2]

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

Color of pixel at coordinate.

Exceptions
EInvalidParamx < 0.
EInvalidParamx >= image.getWidth().
EInvalidParamy < 0.
EInvalidParamy >= image.getHeight().
EInvalidParamz < 0.
EInvalidParamz >= 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
ENullPointerpixels is null.
EInvalidParamx < 0.
EInvalidParamwidth < 0.
EInvalidParamx + width > image.getWidth().
EInvalidParamy < 0.
EInvalidParamheight < 0.
EInvalidParamy + height > image.getHeight().
EInvalidParampixels.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
ENullPointerpixels is null.
EInvalidParamx < 0.
EInvalidParamwidth < 0.
EInvalidParamx + width > image.getWidth().
EInvalidParamy < 0.
EInvalidParamheight < 0.
EInvalidParamy + height > image.getHeight().
EInvalidParamz < 0.
EInvalidParamdepth < 0.
EInvalidParamz + depth > image.getDepth().
EInvalidParampixels.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
EInvalidParamx < 0.
EInvalidParamx >= image.getWidth().
EInvalidParamy < 0.
EInvalidParamy >= 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
EInvalidParamx < 0.
EInvalidParamx >= image.getWidth().
EInvalidParamy < 0.
EInvalidParamy >= image.getHeight().
EInvalidParamz < 0.
EInvalidParamz >= 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
ENullPointerpixels is null.
EInvalidCastelement in pixels is not of type Color.
EInvalidParamx < 0.
EInvalidParamwidth < 0.
EInvalidParamx + width > image.getWidth().
EInvalidParamy < 0.
EInvalidParamheight < 0.
EInvalidParamy + height > image.getHeight().
EInvalidParampixels.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
ENullPointerpixels is null.
EInvalidCastelement in pixels is not of type Color.
EInvalidParamx < 0.
EInvalidParamwidth < 0.
EInvalidParamx + width > image.getWidth().
EInvalidParamy < 0.
EInvalidParamheight < 0.
EInvalidParamy + height > image.getHeight().
EInvalidParamz < 0.
EInvalidParamdepth < 0.
EInvalidParamz + depth > image.getDepth().
EInvalidParampixels.getCount != width * height * depth.

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