PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
Image Class Reference

A bitmap image that can be blitted onto the screen. More...

Inheritance diagram for Image:
Inheritance graph
[legend]

Public Member Functions

number getAlphaValue (Point p)
 get the value for the alpha channel at the given point in the image
 
number getAlphaValue (int x, int y)
 get the value for the alpha channel at the given x, y coordinates in the image
 
number getHeight ()
 get the height in pixels of the image
 
Rect getImageBounds (Point at)
 get image boundary rect, optionally with top left at given point
 
number getOpacity ()
 get opacity of this image
 
Color getPixel (Point p)
 get the pixel data at the given point in the image
 
Color getPixel (int x, int y)
 get the pixel data at the given x, y coordinates in the image
 
Image getSubsection (Quad quad)
 get image that is an arbitrary subsection of this image
 
Image getSubsection (Rect quad)
 get image that is a rectangular subsection of this image
 
Color getTransparentColor ()
 get the color that is used to indicate transparency
 
number getWidth ()
 get the width in pixels of the image
 
number prepareToRasterize ()
 bind the image into an OpenGL texture and free image data from main memory
 
 retainAlpha ()
 retain alpha data for use by Image.getAlphaValue() or per-pixel sprite collisions
 
 retainData ()
 retain pixel data for use by Image.getPixel()
 
 setEdgeClamping (boolean inUseEdgeClamp)
 set whether image uses edge clamping or not
 
 setOpacity (number opacity)
 set opacity of this image
 
Image setTransparentColor (Color inTransparentColor)
 set the color that is used to indicate transparency
 

Detailed Description

A bitmap image that can be blitted onto the screen.

Note
API Stability: 2 - Unstable. The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable. You can create an image directly from a file, or by loading it from resource files with the ResourceManager.
var img = new pdg.Image("myImage.png");

Images are just a data object. Methods in Port are used to draw them onscreen.

See Also
Port.drawImage()
ResourceManager.getImage()

Member Function Documentation

getAlphaValue ( Point  p)

get the value for the alpha channel at the given point in the image

The alpha channel is the transparency of the image. An alpha channel value of 0 is completely transparent, 255 is completely opaque. If the image does not have an alpha channel, then it will return the overall image opacity, as if you had called getOpacity() * 255.

Parameters
pthe point in the image to get the data from
Returns
alpha channel value from 0..255
Note
When an image is first drawn into a port, the image is data is converted into an OpenGL texture and the original image data is purged. Once that happens getAlphaValue() will no longer work. If you need to access the image's alpha channel even after drawing it, use retainAlpha() to prevent the alpha channel from being purged.
See Also
getOpacity()
retainAlpha()
getAlphaValue ( int  x,
int  y 
)

get the value for the alpha channel at the given x, y coordinates in the image

The alpha channel is the transparency of the image. An alpha channel value of 0 is completely transparent, 255 is completely opaque. If the image does not have an alpha channel, then it will return the overall image opacity, as if you had called getOpacity() * 255.

Parameters
xthe x coordinate of the point in the image to get the data from
ythe y coordinate of the point in the image to get the data from
Returns
alpha channel value from 0..255
Note
When an image is first drawn into a port, the image is data is converted into an OpenGL texture and the original image data is purged. Once that happens getAlphaValue() will no longer work. If you need to access the image's alpha channel even after drawing it, use retainAlpha() to prevent the alpha channel from being purged.
See Also
getOpacity()
retainAlpha()
getHeight ( )

get the height in pixels of the image

Returns
the image height in pixels
See Also
getWidth()
getImageBounds()
getImageBounds ( Point  at)

get image boundary rect, optionally with top left at given point

Get a rectangle with the same height and width as the image. The location of the rectangle will either be with the top left at (0,0); or optionally at the point passed in, usually the point at which the image is located in some screen or view coordinate system.

Parameters
atmake the top left of the boundary rect be located at this point. If at is not passed in, the top left will be at (0,0)
Returns
the bounds rectangle for the image, with top left at (0,0) at at the (at.x, at.y) if at was passed in
See Also
getHeight()
getWidth()
getOpacity ( )

get opacity of this image

0.0 - completely transparent to 1.0 - completely solid

Returns
the opacity (0.0 .. 1.0)
See Also
setOpacity()
getPixel ( Point  p)

get the pixel data at the given point in the image

The pixel data will be returned as an RGB Color, including the alpha channel if there is one.

Parameters
pthe point in the image to get the data from
Returns
a Color object with red, green, blue and alpha values
Note
When an image is first drawn into a port, the image is data is converted into an OpenGL texture and the original image data is purged. Once that happens getPixel() will no longer work. If you need to access the image's pixel data even after drawing it, use retainData() to prevent the pixel data from being purged.
See Also
getOpacity()
retainData()
getPixel ( int  x,
int  y 
)

get the pixel data at the given x, y coordinates in the image

The pixel data will be returned as an RGB Color, including the alpha channel if there is one.

Parameters
xthe x coordinate of the point in the image to get the data from
ythe y coordinate of the point in the image to get the data from
Returns
a Color object with red, green, blue and alpha values
Note
When an image is first drawn into a port, the image is data is converted into an OpenGL texture and the original image data is purged. Once that happens getPixel() will no longer work. If you need to access the image's pixel data even after drawing it, use retainData() to prevent the pixel data from being purged.
See Also
getOpacity()
retainData()
getSubsection ( Quad  quad)

get image that is an arbitrary subsection of this image

Returns
a new Image object with the sub image
Note
this is done by referencing the original, the storage space is not duplicated
Parameters
quadthe sub-region desired
getSubsection ( Rect  quad)

get image that is a rectangular subsection of this image

Returns
a new Image object with the sub image
Note
this is done by referencing the original, the storage space is not duplicated
Parameters
quadthe rectangular sub-region desired
getTransparentColor ( )

get the color that is used to indicate transparency

In many cases an image with a single color that is marked as transparent is more space efficient than an entire alpha channel, since you can use RGB instead of RGBA colors (24 rather than 32 bits per pixel).

Returns
Color that is treated as transparent
See Also
setTransparentColor()
getWidth ( )

get the width in pixels of the image

Returns
the image width in pixels
See Also
getHeight()
prepareToRasterize ( )

bind the image into an OpenGL texture and free image data from main memory

You usually won't need to do this explicitly, it is done automatically the first time an image is drawn. This is here to allow you to convert images ahead of time if needed to prevent frame rate hits from conversion while drawing.

See Also
retainAlpha()
retainData()
retainAlpha ( )

retain alpha data for use by Image.getAlphaValue() or per-pixel sprite collisions

Unless retainAlpha is called before the image is converted to an OpenGL texture (ie: the first time it is drawn onscreen), the image alpha channel data will be removed from main memory as soon as it is converted to an OpenGL texture, and getAlphaValue() cannot be used to inspect the contents of the image. Per pixel-sprite collisions won't work either.

See Also
getAlphaValue()
retainData ( )

retain pixel data for use by Image.getPixel()

Unless retainData is called before the image is converted to an OpenGL texture (ie: the first time it is drawn onscreen), the image data will be removed from main memory as soon as it is converted to an OpenGL texture, and getPixel() cannot be used to inspect the contents of the image.

See Also
getPixel()
setEdgeClamping ( boolean  inUseEdgeClamp)

set whether image uses edge clamping or not

Deprecated:
Edge clamping should be on for images except when they are used as repeating textures. In a forthcoming release the drawing engine will automatically do the right thing with edge clamping, and this function will be removed from the image API.

Edge Clamping is useful for applications where you want a single copy of the texture to appear on a large surface. It makes the edges on a large surface align more cleanly with the edges of the image. You should turn off edge clamping with images you intend to use as repeating textures, such as with calls to Port.drawTexture() or Port.drawTexturedSphere().

Fig. 1: Edge Clamping Off vs Edge Clamping On

Fig. 1: Edge Clamping

In the example above you can see faint diagonal white lines on the left hand image (no edge clamping). Those lines are not present in the right hand image after edge clamping is turned on.

Parameters
inUseEdgeClamptrue to use it, false to not
Note
Edge Clamping is on by default for images, so you shouldn't need to change this setting in most cases.
Todo:
Automatically turn off Edge Clamping for images when they are used as textures so setEdgeClamping can be removed from the API.
See Also
Port.drawTexture()
Port.drawTexturedSphere()
setOpacity ( number  opacity)

set opacity of this image

Opacity can be used on an Image regardless of whether it has an alpha channel or not. In images with an alpha channel, the transparency of any given pixel is that pixel's alpha channel value * the image opacity (0.0 .. 1.0).

Parameters
opacitythe desired opacity as range from either (0-255) or (0.0 to 1.0). 0 is completely transparent, 1.0 or 255 is completely solid.
See Also
getOpacity()
setTransparentColor ( Color  inTransparentColor)

set the color that is used to indicate transparency

In many cases an image with a single color that is marked as transparent is more space efficient than an entire alpha channel, since you can use RGB instead of RGBA colors (24 rather than 32 bits per pixel).

Parameters
inTransparentColora color object with red, green and blue value that indicates what RGB value should be treated as transparent
See Also
getTransparentColor()

User Comments