[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Utility Classes

IMG_Raster Methods

The IMG_Raster class encapsulates a 2D image (raster). The class provides a set of methods for creating and manipulating a single raster. Methods are also provided for composite operators that operate using two rasters.

Raster Description

A raster is a 2D image made of a matrix of pixel values. Each pixel contains four channels of information: red, green, blue and alpha (RGBA). Pixels are contained in classes called UT_RGBA or UT_BIG_RGBA.

IMG_Raster can hold a raster at one of two depths: 8 bit or 16 bit. An 8 bit raster provides 8 bits of information for each channel of information (i.e. red, green, blue and alpha). Therefore an 8 bit raster use 32 bits per pixel (UT_RGBA) and a 16 bit raster (UT_BIG_RGBA) use 64 bits per pixel.

Each channel (RGBA) of a raster is quantified by a number from 0 to some maximum (either 255 for 8 bit rasters or 65535 for 16 bit rasters). These channel maximums are defined in the constants CHANNEL_MAX and BIG_CHANNEL_MAX.

The UT_HSVA class assists in manipulating RGBA pixels in a hue, saturation and value space. However, IMG_Raster does not directly store images using HSVA.

Constructing a Raster

  • IMG_Raster()
    This constructs a structure with a null raster (i.e. no raster). A raster can be added by using the size() method.

  • IMG_Raster(short xres, short yres, UT_Raster_Depth depth)
    A raster is constructed with the given size and depth. Use UT_RASTER_8 or UT_RASTER_16 to choose a raster depth.

  • IMG_Raster(short xres, short yres, UT_RGBA *image = 0)
    If an image is supplied, then it becomes part of the IMG_Raster class. It must be of size xres and yres.

    If no image is supplied (or a null pointer is provided), then a new (8 bit) raster is constructed with the given size.

  • IMG_Raster(const IMG_Raster &from)
    A new raster is created with a copy of the from raster.
  • Sizing or Resizing a Raster

  • size(short width, short height, void *newRaster = 0)
    This deletes the current raster (if present) and attaches a new raster of the given size. If newRaster is not supplied (or is null) then a new raster is created.

  • resize(short w, short h, UT_FilterType filter = UT_FILTER_POINT)
    This takes the current raster (if present) and scales it to the given size. The filter value determines what filtering method should be used when scaling the image.

  • resizeCopy(IMG_Raster *src, short w, short h, UT_FilterType filter = UT_FILTER_POINT, float filter_width = 0.0F)
    This deletes the current raster (if present) and copies the source raster (and performs scaling if required). The filter value determines what filtering method should be used when scaling the image. The filter_width is the width of the filter to be used when scaling the image.

    The depth of IMG_Raster is not changed.

  • crop(short x, short y, short w, short h)
    The current raster is cropped to the given size and at the given offset.
  • Finding the Size of the Raster

  • short Xres()
    Returns the current raster width in pixels.

  • short Yres()
    Returns the current raster height in pixels.

  • IMG_Raster_Depth getRasterDepth()
    This will return UT_Raster::UT_RASTER_8 for an 8 bit raster or UT_Raster::UT_RASTER_16 for a 16 bit raster.
  • Accessing the Raster

  • UT_RGBA *getRaster()
    Returns a pointer to the RGBA raster. If there is no associated raster, or the raster is not an 8 bit raster, the method will return a null pointer.

  • UT_BIG_RGBA *getDeepRaster()
    Returns a pointer to the RGBA raster. If there is no associated raster, or the raster is not a 16 bit raster, the method will return a null pointer.

  • void *getVoidRaster()
    Returns a pointer to the RGBA raster. If there is no associated raster, the method will return a null pointer.

    Use getRasterDepth() to determine if the results are of type UT_RGBA or UT_BIG_RGBA.

  • UT_RGBA *getPixel(short x, short y)
    Returns a pointer to the UT_RGBA pixel at the given location. If the location is not within the raster or the raster is not an 8 bit raster, a null pointer will be returned.

  • UT_BIG_RGBA *getDeepPixel(short x, short y)
    Returns a pointer to the UT_BIG_RGBA pixel at the given location. If the location is not within the raster or the raster is not an 16 bit raster, a null pointer will be returned.

  • void *getVoidPixel(short x, short y)
    Returns a pointer to the pixel at the given location. If the location is not within the raster a null pointer will be returned.

    Use getRasterDepth() to determine if the results are of type UT_RGBA or UT_BIG_RGBA.

  • Filter Operations

  • filter(IMG_FilterOp op, float arg = 0.5, short x = 0, short y = 0, short w = 0, short h = 0)
    This method performs a filtering operation on a raster. The arg parameter is a filter parameter that has different effects depending upon the filter operation. The op parameter selects the filter type:

    IMG_FILTER_NONE
    No filtering.
    IMG_FILTER_DISSOLVE
    Dissolve (brighten). An arg of 2 will double the image brightness, a value of 0.5 will halve it.
    IMG_FILTER_GAMMA
    Set the gamma value of the raster.
    IMG_FILTER_QUANTIZE
    Set the number of color levels.
    IMG_FILTER_MONO
    Take colors towards monochrome values. A maximum value of 1.0 will make the image fully monochrome.
    IMG_FILTER_BLUR
    Blur image. A value of 1.0 will blur the image into a single color value.
    IMG_FILTER_EVEN
    Filter and leave just even scanlines. A non-zero value of arg will assign an average value of the even scanlines to the odd scanlines.
    IMG_FILTER_ODD
    Filter and leave just odd scanlines. A non-zero value of arg will assign an average value of the odd scanlines to the even scanlines.
    IMG_FILTER_CHANNEL
    Swap channels. arg is 4 groups (one for each of RGBA) of 3 bit values (red is lowest 3 bits, then green, blue and alpha). Each 3 bit value selects a new channel to be swapped in: 0 for red, 1 for green, 2 for blue, 3 for alpha, 4 for off, 5 for full on and 6 for luminance.
    IMG_FILTER_SHARPEN
    Sharpen image.
    IMG_FILTER_EDGES
    Edge detection. The method setEdgeChannel() must be called to preset the edge detection parameters.
    IMG_FILTER_CHROMAKEY
    Chromakey. The arg parameters is not used, instead the method setChromaKey() must be used to preset the chromakey parameters.
    IMG_FILTER_BUMPMAP
    Create a bump map for use in embossing operations. The method setEdgeChannel() must be used to preset the bump map parameters.

  • rgbaScale(float rrange[2], float grange[2], float brange[2], float arange[2], short x=0, short y=0, short w=0, short h=0)
    This method scales the RGBA values of a raster. Each of RGBA will be scaled or stretched into a range (0 for minimum, 1 for a full value). If supplied, the filter operation will only be applied to the region starting at (x,y) with a width of w and height of h.

  • clear(const UT_RGBA &pixel) and
    clear(const UT_BIG_RGBA &pixel)

    These methods will clear all pixel values of the raster to be the same value as pixel.

  • clear(const UT_Color &color, float alpha = 1.0)
    This method will set all pixel values to the given color and alpha value.
  • Loading and Saving Images

  • int save(const char *pathname) and
    int save(ostream &os, int binary = 1) const;

    These methods save the raster to the given file or ostream. In the first case the file suffix is used to determine the format. The second method saves the raster in a raw dump format or in a uuencoded format if the binary flag is false.

    The return value is 1 upon success and zero upon failure. Errors messages are added to the global Error Manager and may be retrieved from there.

  • int load(const char *pathname, IMG_ScaleOp scaled = IMG_SCALE_NONE, UT_FilterType filter = UT_FILTER_POINT, short size = 100)
    int load(istream &is, int binary = 1)

    These methods load images from either a file in one of the supported Houdini formats or from a stream using the format defined by the corresponding save method.

    The return value is 1 upon success and zero upon failure. Errors messages are added to the global Error Manager and may be retrieved from there.


  • Table of Contents
    Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
    Material & Texture | Objects | Command and Expression | Render Output |
    Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
    Customizing UI | Questions & Answers

    Copyright © 2004 Side Effects Software Inc.
    477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7