ewe.fx
Class PixelBuffer

java.lang.Object
  ewe.fx.PixelBuffer

All Implemented Interfaces:

IImage

public class PixelBuffer

extends Object

implements IImage

A PixelBuffer is used to store ARGB pixel information in an integer array. This is unlike an Image, which uses a system dependant image implementation. However there are some methods, such as draw() which will cause the pixel buffer to create an Image from its data for rendering.

PixelBuffers are generally used for composing complex images with alpha (transparency) channels. This may be necessary because the normal draw operations done via a Graphics object do not support the writing of alpha channel data. For example, you cannot use fillRect() to fill an area of a drawing surface with a particular color that has an alpha channel. However using PixelBuffer.addAlphaChannel(Image im,Color transparent) will allow you to add an alpha channel to a previous drawn image.

Any Images created out of the data from the PixelBuffer will be considered to have an alpha (transparency) channel.

Field Summary

Color	background The background for use when drawing via draw().
static int	PUT_BLEND This is used with put() - it alpha blends in the incoming data with this PixelBuffer's data.
static int	PUT_NONTRANSPARENT_ONLY This is used with put() and the PUT_SET option - it overwrites this PixelBuffer's data with in the incoming data so long as the incoming data is NOT FULLY TRANSPARENT (i.e an alpha value of 0).
static int	PUT_SET This is used with put() - it overwrites this PixelBuffer's data with in the incoming data.
static int	SCALE_KEEP_ASPECT_RATIO An option for scale().
static int	TRANSFORM_MIRROR_HORIZONTAL This is a transformation for the transform() method.
static int	TRANSFORM_MIRROR_VERTICAL This is a transformation for the transform() method.
static int	TRANSFORM_ROTATE_180 This is a transformation for the transform() method.
static int	TRANSFORM_ROTATE_270 This is a transformation for the transform() method.
static int	TRANSFORM_ROTATE_90 This is a transformation for the transform() method.

Fields inherited from interface ewe.fx.IImage

DISABLED, OUTLINED

Constructor Summary

PixelBuffer(IImage from)

PixelBuffer(IImage from, Rect area)

PixelBuffer(IImage from, Rect sourceArea, Dimension newSize, Object useBuffer)

PixelBuffer(int width, int height)

PixelBuffer(int width, int height, int[] bufferToUse)

Method Summary

void	blend(PixelBuffer other, int x, int y) This is the same as put(other,x,y,PUT_BLEND).
void	bufferChanged() If you modify the pixels in the buffer as provided by getBuffer(), then call this method to let the buffer know about the changes.
void	draw(Graphics g, int x, int y, int options) Draw the full image at the specified co-ordinates in the graphics provided.
void	free() This frees system resources associated with the Image.
PixelBuffer	getArea(int x, int y, int width, int height)
Color	getBackground() This returns a background color if one is set for the image.
int[]	getBuffer() This exposes the internal buffer that contains the pixel data.
Graphics	getDrawingBuffer(Rect area, Color transparent, double alphaValue) This will create a drawing surface, initially filled with the supplied transparent color.
int	getHeight() This returns the height of the image.
static PixelBuffer	getImageSection(IImage image, Mask m, Point p, double alphaValue) This gets a section of an Image, starting at a particular point and in a shape represented by Mask.
int[]	getPixels(int[] dest, int offset, int x, int y, int w, int h, int options) Retrieve the pixels from the Image in encoded ARGB values.
static int[]	getPixelsFor(IImage image, int[] dest, int offset, Rect area, int options, Color substituteBackground) This will attempt to get pixels for an IImage.
int	getWidth() This returns the width of the image.
void	put(PixelBuffer other, int x, int y, int operation) This merges the pixels from the other PixelBuffer with the pixels in this PixelBuffer at the specified location.
void	put(PixelBuffer other, int x, int y, int operation, Mask mask) This merges the pixels from the other PixelBuffer with the pixels in this PixelBuffer at the specified location.
void	putDrawingBuffer(int operation) Call this after calling getDrawingBuffer() to update this PixelBuffer with the data you have drawn.
void	putDrawingBuffer(int operation, Mask mask) Call this after calling getDrawingBuffer() to update this PixelBuffer with the data you have drawn, in the area specified by the mask.
PixelBuffer	scale(int newWidth, int newHeight)
PixelBuffer	scale(int newWidth, int newHeight, Object useBuffer)
PixelBuffer	scale(int newWidth, int newHeight, Rect sourceArea, int scaleOptions, Object useBuffer) Scale the PixelBuffer to produce a new PixelBuffer - optionally scaling only a portion of the original PixelBuffer.
void	scaleAlpha(double byHowMuch) This method will go through the pixel buffer data and scale the alpha value of each pixel by the specified amount - not allowing any alpha value to go higher than 1.0.
void	setAlpha(Color transparent, double alpha) This method will go through the pixel buffer data and set the alpha value of each pixel to the specified value (between 0.0 and 1.0), EXCEPT for any pixels that is equal to the transparent Color - those pixels will be set to have an alpha value of 0.
void	setAlpha(double alpha) This method will go through the pixel buffer data and set the alpha value of each pixel to the specified value (between 0.0 and 1.0).
void	setAlpha(Mask mask, double alpha) This method will go through the pixel buffer data and set the alpha value of each pixel which is included in the mask.
Image	toDrawableImage() This returns a new Image (which can be drawn on) from the pixels within this PixelBuffer.
static Object	toIcon(IImage image) This creates a native Icon to be used in (say) a TaskbarWindow or Window, given any IImage object.
Image	toImage() This returns a new ready for display Image with an alpha channel from the pixels within this PixelBuffer.
Mask	toMask() Convert the PixelBuffer to a Mask where all black pixels are opaque and white pixels are transparent.
mImage	toMImage() This returns a new ready for display mImage with an alpha channel from the pixels within this PixelBuffer.
PixelBuffer	transform(int transformation, Object useBuffer) This does one of a number of specific transformations on the PixelBuffer.
boolean	usesAlpha() This always returns true.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

background

public Color background

The background for use when drawing via draw(). This defaults to White.

PUT_BLEND

public static final int PUT_BLEND

This is used with put() - it alpha blends in the incoming data with this PixelBuffer's data.

See Also:

Constant Field Values

PUT_SET

public static final int PUT_SET

This is used with put() - it overwrites this PixelBuffer's data with in the incoming data.

See Also:

Constant Field Values

PUT_NONTRANSPARENT_ONLY

public static final int PUT_NONTRANSPARENT_ONLY

This is used with put() and the PUT_SET option - it overwrites this PixelBuffer's data with in the incoming data so long as the incoming data is NOT FULLY TRANSPARENT (i.e an alpha value of 0).

See Also:

Constant Field Values

SCALE_KEEP_ASPECT_RATIO

public static final int SCALE_KEEP_ASPECT_RATIO

An option for scale().

See Also:

Constant Field Values

TRANSFORM_ROTATE_90

public static final int TRANSFORM_ROTATE_90

This is a transformation for the transform() method.

See Also:

Constant Field Values

TRANSFORM_ROTATE_180

public static final int TRANSFORM_ROTATE_180

This is a transformation for the transform() method.

See Also:

Constant Field Values

TRANSFORM_ROTATE_270

public static final int TRANSFORM_ROTATE_270

This is a transformation for the transform() method.

See Also:

Constant Field Values

TRANSFORM_MIRROR_HORIZONTAL

public static final int TRANSFORM_MIRROR_HORIZONTAL

This is a transformation for the transform() method.

See Also:

Constant Field Values

TRANSFORM_MIRROR_VERTICAL

public static final int TRANSFORM_MIRROR_VERTICAL

This is a transformation for the transform() method.

See Also:

Constant Field Values

Constructor Detail

PixelBuffer

public PixelBuffer(int width,
                   int height,
                   int[] bufferToUse)
            throws IllegalArgumentException

PixelBuffer

public PixelBuffer(int width,
                   int height)
            throws IllegalArgumentException

PixelBuffer

public PixelBuffer(IImage from,
                   Rect area)
            throws IllegalArgumentException

PixelBuffer

public PixelBuffer(IImage from)
            throws IllegalArgumentException

PixelBuffer

public PixelBuffer(IImage from,
                   Rect sourceArea,
                   Dimension newSize,
                   Object useBuffer)

Method Detail

getBuffer

public int[] getBuffer()

This exposes the internal buffer that contains the pixel data.

bufferChanged

public void bufferChanged()

If you modify the pixels in the buffer as provided by getBuffer(), then call this method to let the buffer know about the changes.

getWidth

public int getWidth()

Description copied from interface: IImage

This returns the width of the image.

Specified by:

getWidth in interface IImage

getHeight

public int getHeight()

Description copied from interface: IImage

This returns the height of the image.

Specified by:

getHeight in interface IImage

free

public void free()

Description copied from interface: IImage

This frees system resources associated with the Image.

Specified by:

free in interface IImage

blend

public void blend(PixelBuffer other,
                  int x,
                  int y)

This is the same as put(other,x,y,PUT_BLEND).

put

public void put(PixelBuffer other,
                int x,
                int y,
                int operation)

This merges the pixels from the other PixelBuffer with the pixels in this PixelBuffer at the specified location. This will either replace the pixels in this PixelBuffer (if the PUT_SET) option is used OR it will blend the incoming pixels with the pixels in this PixelBuffer (if the PUT_BLEND) option is used.

Parameters:

other - The other PixelBuffer to merge with this one.

x - The x location where the incoming PixelBuffer should be put.

y - The y location where the incoming PixelBuffer should be put.

operation - This should be either PUT_SET or PUT_BLEND. If PUT_SET is used you can also specify PUT_NONTRANSPARENT_ONLY which tells it to replace pixels in this PixelBuffer ONLY if the corresponding incoming pixels are not fully transparent.

put

public void put(PixelBuffer other,
                int x,
                int y,
                int operation,
                Mask mask)

This merges the pixels from the other PixelBuffer with the pixels in this PixelBuffer at the specified location. This will either replace the pixels in this PixelBuffer (if the PUT_SET) option is used OR it will blend the incoming pixels with the pixels in this PixelBuffer (if the PUT_BLEND) option is used.

Parameters:

other - The other PixelBuffer to merge with this one.

x - The x location where the incoming PixelBuffer should be put.

y - The y location where the incoming PixelBuffer should be put.

operation - This should be either PUT_SET or PUT_BLEND.

mask - A mask specifying which incoming pixels should be merged with the Pixels in this PixelBuffer.

setAlpha

public void setAlpha(double alpha)

This method will go through the pixel buffer data and set the alpha value of each pixel to the specified value (between 0.0 and 1.0).

Parameters:

alpha - The alpha value between 0.0 and 1.0

setAlpha

public void setAlpha(Color transparent,
                     double alpha)

This method will go through the pixel buffer data and set the alpha value of each pixel to the specified value (between 0.0 and 1.0), EXCEPT for any pixels that is equal to the transparent Color - those pixels will be set to have an alpha value of 0. If this is null, then all pixels will have the alpha value set to the same.

Parameters:

transparent - the transparent Color.

alpha - The alpha value between 0.0 and 1.0

setAlpha

public void setAlpha(Mask mask,
                     double alpha)

This method will go through the pixel buffer data and set the alpha value of each pixel which is included in the mask. Pixels not in the mask will have their pixel values set to 0.

Parameters:

mask - The pixel mask.

alpha - The alpha value between 0.0 and 1.0

scaleAlpha

public void scaleAlpha(double byHowMuch)

This method will go through the pixel buffer data and scale the alpha value of each pixel by the specified amount - not allowing any alpha value to go higher than 1.0. Note that totally transparent pixels (alpha value of 0) will always remain fully transparent.

getBackground

public Color getBackground()

Description copied from interface: IImage

This returns a background color if one is set for the image.

Specified by:

getBackground in interface IImage

usesAlpha

public boolean usesAlpha()

This always returns true.

Specified by:

usesAlpha in interface IImage

getDrawingBuffer

public Graphics getDrawingBuffer(Rect area,
                                 Color transparent,
                                 double alphaValue)

This will create a drawing surface, initially filled with the supplied transparent color. After calling this method, draw on the surface using the supplied Graphics and when complete call putDrawingBuffer(int operation) to put back the drawing buffer pixels into the original PixelBuffer.

Parameters:

area - An area within the pixbuf to use - will default to the entire area if null.

transparent - The initial color to consider the transparent color when putting the area back into the PixelBuffer, or Color(80,255,80) if none is supplied.

alphaValue - the alphaValue to set all the non-transparent pixels to (between 0.0 and 1.0).

Returns:

a Graphics object that you can use to draw on.

putDrawingBuffer

public void putDrawingBuffer(int operation)

Call this after calling getDrawingBuffer() to update this PixelBuffer with the data you have drawn. This will put the data that was drawn onto the Graphics created by getDrawingBuffer(), using one of the PUT_ operations.

Parameters:

operation - One of PUT_BLEND or PUT_SET

putDrawingBuffer

public void putDrawingBuffer(int operation,
                             Mask mask)

Call this after calling getDrawingBuffer() to update this PixelBuffer with the data you have drawn, in the area specified by the mask. This will put the data that was drawn onto the Graphics created by getDrawingBuffer(), using one of the PUT_ operations.

Parameters:

operation - One of PUT_BLEND or PUT_SET

mask - A mask specifying which pixels should be put. Any pixels not in this area are unchanged.

toImage

public Image toImage()

This returns a new ready for display Image with an alpha channel from the pixels within this PixelBuffer. Note that the toMImage() method is more useful if you intend to display the image, since an mImage() displays more effeciently depending on the nature of the image.

toDrawableImage

public Image toDrawableImage()

This returns a new Image (which can be drawn on) from the pixels within this PixelBuffer. Note that the toMImage() method is more useful if you intend to display the image, since an mImage() displays more effeciently depending on the nature of the image.

toMImage

public mImage toMImage()

This returns a new ready for display mImage with an alpha channel from the pixels within this PixelBuffer. An mImage will display more effeciently than an Image depending on the nature of the image.

draw

public void draw(Graphics g,
                 int x,
                 int y,
                 int options)

Description copied from interface: IImage

Draw the full image at the specified co-ordinates in the graphics provided.

Specified by:

draw in interface IImage

getArea

public PixelBuffer getArea(int x,
                           int y,
                           int width,
                           int height)
                    throws IllegalArgumentException

Throws:

IllegalArgumentException

scale

public PixelBuffer scale(int newWidth,
                         int newHeight,
                         Object useBuffer)

scale

public PixelBuffer scale(int newWidth,
                         int newHeight)

toMask

public Mask toMask()

Convert the PixelBuffer to a Mask where all black pixels are opaque and white pixels are transparent.

scale

public PixelBuffer scale(int newWidth,
                         int newHeight,
                         Rect sourceArea,
                         int scaleOptions,
                         Object useBuffer)
                  throws IllegalArgumentException

Scale the PixelBuffer to produce a new PixelBuffer - optionally scaling only a portion of the original PixelBuffer.

Parameters:

newWidth - The width of the new PixelBuffer.

newHeight - The height of the new PixelBuffer.

sourceArea - An optional rectangle specifying the source area in this PixelBuffer. If it is null then entire area is used.

scaleOptions - This can be zero or SCALE_KEEP_ASPECT_RATIO.

useBuffer - An optional re-usable buffer to use for the data calculations. It can be a ByteArray or a byte [] object or it can be a PixelBuffer. If useBuffer is a PixelBuffer its data buffer will be used (if big enough) and its width and height will be adjusted and that PixelBuffer will be returned.

Returns:

The new scaled PixelBuffer or the useBuffer argument if it was a PixelBuffer.

Throws:

IllegalArgumentException - If there was an error with any of the arguments.

transform

public PixelBuffer transform(int transformation,
                             Object useBuffer)

This does one of a number of specific transformations on the PixelBuffer.

Parameters:

transformation - One of the TRANSFORM_XXX values.

useBuffer - An optional byte [] or ByteArray object to use as the buffer for the newly created PixelBuffer

Returns:

A new PixelBuffer holding the transformed image (this may be of different dimensions to the original).

getPixels

public int[] getPixels(int[] dest,
                       int offset,
                       int x,
                       int y,
                       int w,
                       int h,
                       int options)
                throws IllegalArgumentException

Description copied from interface: IImage

Retrieve the pixels from the Image in encoded ARGB values. If the usesAlpha() method returns false, then the A component of each pixel value (the top 8 bits) should be ignored.

Specified by:

getPixels in interface IImage

Parameters:

dest - The destination int array. If this is null then a new array should be created.

offset - The offset into the array to start placing pixels.

x - the x co-ordinate within the image.

y - the y co-ordinate within the image.

w - the width of the pixel block to get.

h - the height of the pixel block to get.

options - options for retrieving pixels - currently unused.

Returns:

The array containing the pixels, or null if getting pixels is not supported.

Throws:

IllegalArgumentException

getPixelsFor

public static int[] getPixelsFor(IImage image,
                                 int[] dest,
                                 int offset,
                                 Rect area,
                                 int options,
                                 Color substituteBackground)

This will attempt to get pixels for an IImage. If the IImage cannot provide the pixels directly, then a PixelBuffer will be created and the IImage drawn on it. Then the pixels from the pixel buffer will be returned.

getImageSection

public static PixelBuffer getImageSection(IImage image,
                                          Mask m,
                                          Point p,
                                          double alphaValue)

This gets a section of an Image, starting at a particular point and in a shape represented by Mask.

Parameters:

image - The original image.

m - The mask representing the bits of the Image that should be taken. This Mask can be smaller than the full image - the p parameter specifies where in the image the section should be taken from.

p - The point in the Image where the section should be taken from.

alphaValue - An alpha value to be applied to all pixels taken from the Image.

Returns:

A new PixelBuffer that contains the pixels taken from the Image. All pixels which were excluded from the Mask will be fuly transparent.

toIcon

public static Object toIcon(IImage image)

This creates a native Icon to be used in (say) a TaskbarWindow or Window, given any IImage object.