processing.core
Class PImage

java.lang.Object
  processing.core.PImage

All Implemented Interfaces:

java.lang.Cloneable, PConstants

Direct Known Subclasses:

Capture, Movie, PGraphics

public class PImage
extends java.lang.Object
implements PConstants, java.lang.Cloneable

Storage class for pixel data. This is the base class for most image and pixel information, such as PGraphics and the video library classes.

Code for copying, resizing, scaling, and blending contributed by toxi.

format

public int format

Format for this image, one of RGB, ARGB or ALPHA. note that RGB images still require 0xff in the high byte because of how they'll be manipulated by other functions

pixels

public int[] pixels

width

public int width

height

public int height

parent

public PApplet parent

Path to parent object that will be used with save(). This prevents users from needing savePath() to use PImage.save().

PImage

public PImage()

Create an empty image object, set its format to RGB. The pixel array is not allocated.

PImage

public PImage(int width,
              int height)

Create a new RGB (alpha ignored) image of a specific size. All pixels are set to zero, meaning black, but since the alpha is zero, it will be transparent.

PImage

public PImage(int width,
              int height,
              int format)

PImage

public PImage(java.awt.Image img)

Construct a new PImage from a java.awt.Image. This constructor assumes that you've done the work of making sure a MediaTracker has been used to fully download the data and that the img is valid.

init

public void init(int width,
                 int height,
                 int format)

Function to be used by subclasses of PImage to init later than at the constructor, or re-init later when things changes. Used by Capture and Movie classes (and perhaps others), because the width/height will not be known when super() is called. (Leave this public so that other libraries can do the same.)

getImage

public java.awt.Image getImage()

Returns a BufferedImage from this PImage.

setCache

public void setCache(java.lang.Object parent,
                     java.lang.Object storage)

Store data of some kind for a renderer that requires extra metadata of some kind. Usually this is a renderer-specific representation of the image data, for instance a BufferedImage with tint() settings applied for PGraphicsJava2D, or resized image data and OpenGL texture indices for PGraphicsOpenGL.

getCache

public java.lang.Object getCache(java.lang.Object parent)

Get cache storage data for the specified renderer. Because each renderer will cache data in different formats, it's necessary to store cache data keyed by the renderer object. Otherwise, attempting to draw the same image to both a PGraphicsJava2D and a PGraphicsOpenGL will cause errors.

Parameters:

parent - The PGraphics object (or any object, really) associated

Returns:

data stored for the specified parent

removeCache

public void removeCache(java.lang.Object parent)

Remove information associated with this renderer from the cache, if any.

Parameters:

parent - The PGraphics object whose cache data should be removed

isModified

public boolean isModified()

setModified

public void setModified()

setModified

public void setModified(boolean m)

loadPixels

public void loadPixels()

Call this when you want to mess with the pixels[] array.

For subclasses where the pixels[] buffer isn't set by default, this should copy all data into the pixels[] array

updatePixels

public void updatePixels()

Call this when finished messing with the pixels[] array.

Mark all pixels as needing update.

updatePixels

public void updatePixels(int x,
                         int y,
                         int w,
                         int h)

Mark the pixels in this region as needing an update.

This is not currently used by any of the renderers, however the api is structured this way in the hope of being able to use this to speed things up in the future.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Duplicate an image, returns new PImage object. The pixels[] array for the new object will be unique and recopied from the source image. This is implemented as an override of Object.clone(). We recommend using get() instead, because it prevents you from needing to catch the CloneNotSupportedException, and from doing a cast from the result.

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

resize

public void resize(int wide,
                   int high)

Resize this image to a new width and height. Use 0 for wide or high to make that dimension scale proportionally.

get

public int get(int x,
               int y)

Returns an ARGB "color" type (a packed 32 bit int with the color. If the coordinate is outside the image, zero is returned (black, but completely transparent).

If the image is in RGB format (i.e. on a PVideo object), the value will get its high bits set, just to avoid cases where they haven't been set already.

If the image is in ALPHA format, this returns a white with its alpha value set.

This function is included primarily for beginners. It is quite slow because it has to check to see if the x, y that was provided is inside the bounds, and then has to check to see what image type it is. If you want things to be more efficient, access the pixels[] array directly.

get

public PImage get(int x,
                  int y,
                  int w,
                  int h)

Grab a subsection of a PImage, and copy it into a fresh PImage. As of release 0149, no longer honors imageMode() for the coordinates.

get

public PImage get()

Returns a copy of this PImage. Equivalent to get(0, 0, width, height).

set

public void set(int x,
                int y,
                int c)

Set a single pixel to the specified color.

set

public void set(int x,
                int y,
                PImage src)

Efficient method of drawing an image's pixels directly to this surface. No variations are employed, meaning that any scale, tint, or imageMode settings will be ignored.

mask

public void mask(int[] alpha)

Set alpha channel for an image. Black colors in the source image will make the destination image completely transparent, and white will make things fully opaque. Gray values will be in-between steps.

Strictly speaking the "blue" value from the source image is used as the alpha color. For a fully grayscale image, this is correct, but for a color image it's not 100% accurate. For a more accurate conversion, first use filter(GRAY) which will make the image into a "correct" grayscake by performing a proper luminance-based conversion.

mask

public void mask(PImage alpha)

Set alpha channel for an image using another image as the source.

filter

public void filter(int kind)

Method to apply a variety of basic filters to this image.

• filter(BLUR) provides a basic blur.
• filter(GRAY) converts the image to grayscale based on luminance.
• filter(INVERT) will invert the color components in the image.
• filter(OPAQUE) set all the high bits in the image to opaque
• filter(THRESHOLD) converts the image to black and white.
• filter(DILATE) grow white/light areas
• filter(ERODE) shrink white/light areas

Luminance conversion code contributed by toxi

Gaussian blur code contributed by Mario Klingemann

filter

public void filter(int kind,
                   float param)

Method to apply a variety of basic filters to this image. These filters all take a parameter.

• filter(BLUR, int radius) performs a gaussian blur of the specified radius.
• filter(POSTERIZE, int levels) will posterize the image to between 2 and 255 levels.
• filter(THRESHOLD, float center) allows you to set the center point for the threshold. It takes a value from 0 to 1.0.

Gaussian blur code contributed by Mario Klingemann and later updated by toxi for better speed.

copy

public void copy(int sx,
                 int sy,
                 int sw,
                 int sh,
                 int dx,
                 int dy,
                 int dw,
                 int dh)

Copy things from one area of this image to another area in the same image.

copy

public void copy(PImage src,
                 int sx,
                 int sy,
                 int sw,
                 int sh,
                 int dx,
                 int dy,
                 int dw,
                 int dh)

Copies area of one image into another PImage object.

blendColor

public static int blendColor(int c1,
                             int c2,
                             int mode)

Blend two colors based on a particular mode.

• REPLACE - destination colour equals colour of source pixel: C = A. Sometimes called "Normal" or "Copy" in other software.
• BLEND - linear interpolation of colours: C = A*factor + B
• ADD - additive blending with white clip: C = min(A*factor + B, 255). Clipped to 0..255, Photoshop calls this "Linear Burn", and Director calls it "Add Pin".
• SUBTRACT - substractive blend with black clip: C = max(B - A*factor, 0). Clipped to 0..255, Photoshop calls this "Linear Dodge", and Director calls it "Subtract Pin".
• DARKEST - only the darkest colour succeeds: C = min(A*factor, B). Illustrator calls this "Darken".
• LIGHTEST - only the lightest colour succeeds: C = max(A*factor, B). Illustrator calls this "Lighten".
• DIFFERENCE - subtract colors from underlying image.
• EXCLUSION - similar to DIFFERENCE, but less extreme.
• MULTIPLY - Multiply the colors, result will always be darker.
• SCREEN - Opposite multiply, uses inverse values of the colors.
• OVERLAY - A mix of MULTIPLY and SCREEN. Multiplies dark values, and screens light values.
• HARD_LIGHT - SCREEN when greater than 50% gray, MULTIPLY when lower.
• SOFT_LIGHT - Mix of DARKEST and LIGHTEST. Works like OVERLAY, but not as harsh.
• DODGE - Lightens light tones and increases contrast, ignores darks. Called "Color Dodge" in Illustrator and Photoshop.
• BURN - Darker areas are applied, increasing contrast, ignores lights. Called "Color Burn" in Illustrator and Photoshop.

A useful reference for blending modes and their algorithms can be found in the SVG specification.

It is important to note that Processing uses "fast" code, not necessarily "correct" code. No biggie, most software does. A nitpicker can find numerous "off by 1 division" problems in the blend code where >>8 or >>7 is used when strictly speaking /255.0 or /127.0 should have been used.

For instance, exclusion (not intended for real-time use) reads r1 + r2 - ((2 * r1 * r2) / 255) because 255 == 1.0 not 256 == 1.0. In other words, (255*255)>>8 is not the same as (255*255)/255. But for real-time use the shifts are preferrable, and the difference is insignificant for applications built with Processing.

public void blend(int sx,
                  int sy,
                  int sw,
                  int sh,
                  int dx,
                  int dy,
                  int dw,
                  int dh,
                  int mode)

public void blend(PImage src,
                  int sx,
                  int sy,
                  int sw,
                  int sh,
                  int dx,
                  int dy,
                  int dw,
                  int dh,
                  int mode)

public void save(java.lang.String path)