Brief Index      Full Index      I.M. Reference

Insert_Image


Functions

void Insert_Image (double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
HC_KEY KInsert_Image (double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
void QInsert_Image (const char *segment, double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
HC_KEY QKInsert_Image (const char *segment, double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
void Insert_Image_By_Ref (double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
HC_KEY KInsert_Image_By_Ref (double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
void QInsert_Image_By_Ref (const char *segment, double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
HC_KEY QKInsert_Image_By_Ref (const char *segment, double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
void DInsert_Image (double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
HC_KEY DKInsert_Image (double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
void DQInsert_Image (const char *segment, double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)
HC_KEY DQKInsert_Image (const char *segment, double x, double y, double z, const char *format, int width, int height, const HC_PIXEL *data)

Function Documentation

void Insert_Image ( double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Inserts a pixel-based image in the HOOPS database.

Parameters:
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.
Supported Options:
down-sample, local, name, mapped 16, mapped 8, mapped, RGB, RGBA, size, texture options,

DETAILS

Images are intended for the display of raster arrays of pixels. They are unique in that they are laid out in terms of screen space---once the center has been located (transformed from object space) everything else is defined solely in terms of the pixels on the screen of your current display device. Images are extremely display-dependent. Images look different on different devices depending on their resolutions, aspect ratios, and, indeed, whether or not they actually display in terms of pixels.

The _By_Ref() ("by reference") routines differ from the regular routines. The system is allowed not to make a copy of your data (at the system's option) but instead will remember where your image was located. Then, whenever the pixels need to be redisplayed, the image originally passed in data is used, not an internal copy. This can speed up the call to Insert_Image() and it can save memory. But be careful---when you insert "by reference", you are guaranteeing that data is going to remain valid and you're not going to touch it (except via Edit_Image() ) until such time as the whole Image database entry gets deleted. Also, as mentioned, the system can make a copy anyhow if it needs to. So don't assume Edits will be readable in the original array.

The following choices for "format" are recognized:

[no] down-sample
If this is set, images will have a bilinear filter applied to them. This typically makes images look smoother, especially if zoomed in. However, if there are hard edges (e.g. a checker board) it can make the image look unnecessarily blurry. Default = "down-sample"

[no] local
If set, the implicit texture created will be local to the currently open segment. Default = "no local"

name = <identifier>
The name which will be applied to the texture that will be implicitly defined with the options specified in 'texture options'. Providing no texture option string will mean that a texture is then created with default texture options. If you do not want an implicitly texture created you should not provide a name to the image.

mapped 16
Treats data as a two-dimensional array of 16-bit color map indices (two consecutive bytes per pixel). The byte ordering within data is identical to casting an array of short integers. The pixel values defined here are not full-fledged HOOPS color triplets or strings; they are just look-up indices. This lets you "color by number", while the actual colors are defined indirectly by the current "Color Map" attribute. You must define an appropriate color map to match your image. Also, the color look-up is performed at Update time, not just at declaration time---changes to the color map will be reflected in the appearance of images that already exist.

mapped 8
Identical to "mapped 16", but treats data as a two-dimensional array of 8-bit color map indices.

mapped
"Mapped" is a convenience synonym for "mapped 8".

RGB
Treats data as a two-dimensional array of pixels, where each pixel's color is described by three bytes: one for the red, green, and blue intensities. The first three bytes in data describe the red, green, and blue components of the upper-left-most image pixel. The following three data bytes describe the next pixel to the right. The next scan line begins at (width*3) in the array. When using RGB formatted images on color-mapped devices (such as 8-bit plane displays), HOOPS will "dither" the image using fixed colors. The larger a fixed color table you choose via Set_Driver_Options() , the more accurate the dither will be. If you plan on using the virtual "image driver", you must select the RGB format for the image into which the driver will draw. For full information on scan-converting into a HOOPS image, see the "Image Driver" section of your installation guide.

RGBA
Treats data as a two-dimensional array of pixels, where each pixel's color is described by four bytes: one for each of the red, green, and blue intensities, along with one for alpha. A non-zero alpha value indicates that the pixel is illuminated using the RGB. The layout of the data matches that of RGB with the exception that four instead of three bytes per pixel are used.

size = ((float) width units, (float) height units)
size = <float> units

Scale for an image where units is either "oru", "sru" or "pixels". "size = <float> units" will preserve aspect ratio.

texture options = (...)
Options for the implicit texture created for the image. See Define_Texture() for the list of recognized options.

NOTES

If you have a choice, (if it is possible to define the picture so) it is better to use lines, polygons, etc., rather than images, since that way 1) your picture's appearance will be independent of the display device, and 2) you will have more ways to manipulate it. Images are appropriate when that's the format of the data arriving from the outside world, or if you are drawing photograph-like pictures.

If an image is not completely contained within the current window, it will be clipped appropriately.

You might find it convenient to set up a camera volume that matches the number of pixels on your screen. This will simplify aligning adjacent images exactly.

If you wish to transform an image (rotate, scale, etc.), any named image can be "painted" onto a shell or mesh face using a process called "texture mapping" (see Define_Texture() for details).

If there is an error the KInsert routine returns a-1.

RESTRICTIONS

Images are pixel-based in HOOPS and do not scale. In addition, image data does not currently obey the force back and white driver option.

See also:
Set_Color_Map, Edit_Image, Move_Image, Show_Image, Modify_Color_Map, Renumber_Key, Set_Visibility, Set_Driver_Options, Define_Texture, Set_Camera_By_Volume.

HC_KEY KInsert_Image ( double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image(), but returns an HC_KEY to the object.

Parameters:
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.
Returns:
key

DETAILS

No additional details. See Insert_Image()

void QInsert_Image ( const char *  segment,
double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image(), but operates on a given segment rather than the currently open one.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.

DETAILS

No additional details. See Insert_Image()

HC_KEY QKInsert_Image ( const char *  segment,
double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image(), but operates on a given segment and returns an HC_KEY to the object.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.
Returns:
key

DETAILS

No additional details. See Insert_Image()

void Insert_Image_By_Ref ( double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image(), but does not create a copy of the image data within HOOPS.

Parameters:
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.

DETAILS

No additional details. See Insert_Image()

NOTES

  • If an image inserted by reference is directly edited, the user should call HC_Edit_Image with a edit size of 0 to ensure that the image gets updated properly.

HC_KEY KInsert_Image_By_Ref ( double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image_By_Ref(), but returns an HC_KEY to the image.

Parameters:
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.
Returns:
key

DETAILS

No additional details. See Insert_Image()

void QInsert_Image_By_Ref ( const char *  segment,
double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image_By_Ref(), but inserts the image in a given segment.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.

DETAILS

No additional details. See Insert_Image()

HC_KEY QKInsert_Image_By_Ref ( const char *  segment,
double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image_By_Ref(), but inserts the image in a given segment and returns an HC_KEY to the image.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.
Returns:
key

DETAILS

No additional details. See Insert_Image()

void DInsert_Image ( double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to Insert_Image() but accepts and/or returns double-precision values. This command can only be used when the application source includes the HOOPS double-precision header, hcd.h.

Parameters:
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.

DETAILS

No additional details. See Insert_Image().

HC_KEY DKInsert_Image ( double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to DInsert_Image(), but returns an HC_KEY to the object.

Parameters:
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.
Returns:
key

DETAILS

No additional details. See Insert_Image()

void DQInsert_Image ( const char *  segment,
double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to DInsert_Image(), but operates on a given segment rather than the currently open one.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.

DETAILS

No additional details. See Insert_Image()

HC_KEY DQKInsert_Image ( const char *  segment,
double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const HC_PIXEL *  data 
)

Similar to DInsert_Image(), but operates on a given segment and returns an HC_KEY to the object.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
x - The x-coordinate of the center of the image.
y - The y-coordinate of the center of the image.
z - The z-coordinate of the center of the image.
format - A description of how data in the data array is packed
width - The number of columns of pixels in this image. Must be a positive number.
height - The number of rows of pixels in this image. Must be a positive number.
data - An array of bytes, packed in accordance with format, that describes the colors of each pixel in the image.
Returns:
key

DETAILS

No additional details. See Insert_Image()

Main Index
Brief Index      Full Index      I.M. Functions