Insert_Image

Functions

HC_KEY DInsert_Image (double x, double y, double z, const char *format, int width, int height, const void *data)
 Similar to Insert_Image(), but accepts parameters of type double for increased precision. More...
 
HC_KEY DInsert_Image_By_Ref (double x, double y, double z, const char *format, int width, int height, const void *data)
 Similar to Insert_Image_By_Ref(), but operates on double-precision data. More...
 
HC_KEY Insert_Image (double x, double y, double z, const char *format, int width, int height, const void *data)
 Inserts a pixel-based image in the HOOPS Visualize database. More...
 
HC_KEY Insert_Image_By_Ref (double x, double y, double z, const char *format, int width, int height, const void *data)
 Similar to Insert_Image(), but does not create a copy of the image data within HOOPS. More...
 

Detailed Description

Function Documentation

◆ DInsert_Image()

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

Similar to Insert_Image(), but accepts parameters of type double for increased precision.

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
The key to the inserted geometry, or -1 if an error occurred.

◆ DInsert_Image_By_Ref()

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

Similar to Insert_Image_By_Ref(), but operates on double-precision data.

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
The key to the inserted geometry.

◆ Insert_Image()

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

Inserts a pixel-based image in the HOOPS Visualize 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.
Returns
The key to the inserted geometry, or -1 if an error occurred.
Supported Options:
discard, down-sample, grayscale, local, name, mapped 16, mapped 8, mapped, RGB, RGBA, size, compression quality, 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:

discard
If set, then the image data will be purged from the HOOPS data once the texture is loaded into video memory. This will result in the memory associated with that image being returned to the system. Note, the image database item will remain in the HOOPS database and can be returned to the user via a call to Show_Image().

[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"

grayscale
Treats data as a two-dimensional array of single byte entries where each byte defines the luminance of the pixel.

[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 = &lt;float&gt; units" will preserve aspect ratio.
compression quality = <float>
Compression quality is a floating point value between 0 and 1. This option will allow HOOPS to choose from one of the compression schemes offered by the underlying hardware drivers. This option can be ignored depending on the capabilities of the underlying hardware. The default will be 1, i.e. no compression.

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).

The double parameters are internally truncated to float. If you require extra precision, use this function's double-precision variant, DInsert_Image.

RESTRICTIONS

Images are pixel-based in HOOPS and do not scale. In addition, image data does not currently obey the force grayscale 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.

◆ Insert_Image_By_Ref()

HC_KEY Insert_Image_By_Ref ( double  x,
double  y,
double  z,
const char *  format,
int  width,
int  height,
const void *  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.
Returns
The key to the inserted geometry.

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.