In addition to the function calls in the previous section, convenience functions exist that simplify accessing frame buffers and performing simple operations on colors. These functions are all implemented on top of the (deprecated) miIMG_ACCESS macro. All these functions do nothing or return defaults if the image pointer is 0, or if the x, y coordinate is out of bounds. They do not check whether the frame buffer has the correct data type.
void mi_img_mode(
miBoolean desaturate,
miBoolean dither,
miBoolean no_premult,
double gamma)
Deprecated Set the mode for all future mi_img_put_color and mi_img_get_color calls. This should be used with care, because if the arguments change between a put and a get, get will not return the same value stored with put. Desaturation specifies the clipping method for out-of-range color components: if desaturation is turned on, the color is faded to white; if it is turned off (default), individual components are clipped if they exceed 1. Dithering, if enabled, adds a random constant to each component such that the lowest bit of the quantized component is jittered to avoid banding. If no_premult is true, the standard color premultiplication is undone before quantization, by dividing R, G, and B by alpha. If the gamma factor is not 1.0, gamma correction is applied to colors before quantization (floating-point and RGBE colors are not gamma-corrected). If any of the arguments has the integer value -1, it is ignored and not set (this requires casting).
mental ray has moved the flags and gamma into the options. There is still a mi_img_mode function, which merely passes the tag of the options structure, and is used internally only.
void mi_img_getmode(
miBoolean *desaturate,
miBoolean *dither,
miBoolean *no_premult,
double *gamma)
Deprecated Retrieve the current modes as previously set with mi_img_mode or the defaults. If an argument pointer is null, no value is stored.
void mi_img_clip_color(
miImg_image *image,
miColor color)
Applies the clipping and desaturation specified with mi_img_mode to a single RGBA color. If the color frame buffer img is a floating-point frame buffer, do nothing; otherwise either desaturate or clip the RGBA components to bring them into the range [0...1]. If any of RGB exceed A, set A to the maximum of RGB. Gamma is not applied, and neither is un-premultiplication because that is a function of quantization. Internally, raylib always works with premultiplied colors.
void mi_img_put_color(
miImg_image *image,
miColor *color,
int x,
int y)
Store the color color in the color frame buffer image at coordinate x y, after performing desaturation or color clipping, gamma compensation, dithering, and compensating for premultiplication, if enabled by the mi_img_mode call. This function works with 1, 3, or 4 components per pixel, and with 8, 16, or 32 bits per component. The normal range for non-floating point R, G, B, and A color components is [0, 1] inclusive.
void mi_img_get_color(
miImg_image *image,
miColor *color,
int x,
int y)
This is the reverse function to mi_img_put_color, it returns the color stored in a frame buffer at the specified coordinates. Gamma compensation and premultiplication, if enabled by mi_img_mode, are applied in reverse. (Note that this is done correctly only if the mi_img_put_color has not been called with different arguments since the corresponding call to mi_img_put_color.) The returned color may differ from the original color given to mi_img_put_color because of color clipping and color quantization. If the frame buffer has only one component, all four components of color will have the same value; if the frame buffer has three components, alpha is set to 1. If the frame buffer pointer is 0 or if the coordinates are out of bounds, all components are set to 0.
void mi_img_get_color_square(
miImg_image *image,
miColor *color,
int x,
int y)
This function is very similar to mi_img_put_color, except that it returns four color values: Those at (x,y), (x+1,y), (x,y+1) and (x+1,y+1) . The parameter color must point to the array of four miColor structures that will receive the color values, in the order given above. This function is primarily intended to be used by texture lookup functions such as mi_lookup_color_texture that need to do bilinear interpolation of four colors. It saves the overhead of four function calls and redundant validation checks. Note that unlike some of the other functions, it doesn't check the range of x and y, and it is up to the caller to ensure that they are in range.
void mi_img_put_scalar(
miImg_image *image,
miScalar scalar,
int x,
int y)
Store the scalar scalar in the scalar frame buffer image at coordinate x y, after clipping to the range [0, 1]. Scalars are stored as 8-bit or 16-bit unsigned values. This function is intended for scalar texture files of type miIMG_S or miIMG_S_16.
void mi_img_get_scalar(
miImg_image *image,
miScalar *scalar,
int x,
int y)
This is the reverse function to mi_img_put_scalar, it returns the scalar stored in a frame buffer at the specified coordinates, converted to a scalar in the range [0, 1]. If the frame buffer pointer is 0 or if the coordinates are out of bounds, the scalar is set to 0.
void mi_img_put_vector(
miImg_image *image,
miVector *vector,
int x,
int y)
Store the X and Y components of the vector vector in the vector frame buffer image at coordinate x y, after clipping to the range [-1, 1]. Vectors are stored as 16-bit signed values. This function is intended for vector texture files of type miIMG_VTA or miIMG_VTS.
void mi_img_get_vector(
miImg_image *image,
miVector *vector,
int x,
int y)
This is the reverse function to mi_img_put_vector, it returns the UV vector stored in a frame buffer at the specified coordinates, with coordinates converted to the range [-1, 1]. The Z component of the vector is always set to 0. If the frame buffer pointer is 0 or if the coordinates are out of bounds, all components are set to 0.
void mi_img_put_depth(
miImg_image *image,
float depth,
int x,
int y)
Store the depth value depth in the frame buffer image at the coordinates x y. The depth value is not changed in any way. The standard interpretation of the depth is the Z coordinate of objects relative to the camera.
void mi_img_get_depth(
miImg_image *image,
float *depth,
int x,
int y)
Read the depth value to the float pointed to by depth from frame buffer image at the coordinates x y. If the image pointer is 0, or if the coordinates are out of bounds, return the MAX_FLT constant from limits.h.
void mi_img_put_normal(
miImg_image *image,
miVector *normal,
int x,
int y)
Store the normal vector normal in the frame buffer image at the coordinates x y. The normal vector is not changed in any way.
void mi_img_get_normal(
miImg_image *image,
miVector *normal,
int x,
int y)
Read the normal vector normal from frame buffer image at the coordinates x y. If the image pointer is 0, or if the coordinates are out of bounds, return a null vector.
void mi_img_put_label(
miImg_image *image,
miUint label,
int x,
int y)
Store the label value label in the frame buffer image at the coordinates x y. The label value is not changed in any way.
void mi_img_get_label(
miImg_image *image,
miUint *label,
int x,
int y)
Read the label value to the unsigned integer pointed to by label from frame buffer image at the coordinates x y. If the image pointer is 0, or if the coordinates are out of bounds, return 0.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.