Image Methods and Types


The image library handles images in memory. The only format for these images is 32 bit ARGB (alpha,red,green,blue). It has an interface which may be used. Interfaces are single pointers to tables of functions. This library and the display library may be dynamically switched using interfaces. Three libraries currently implement these functions. Image, built from src/imglib; Display, built from src/display; cimage, also built from src/display. Display and cimage both implement additional wrappers on most of these functions such that independant images clip other images... This also brings a close relation to render.h.

Include

#include <image.h>

Project Location

src/imglib
-or-
src/displaylib

Library

image
-or-
cimage -or- display
-or-
interface

Required Libraries

shmem, syslog
(for display/cimage) msgclient

Types

IMAGE_INTERFACE PIMAGE_INTERFACEThe table of functions to interface to this library. Defining the symbol USE_IMAGE_INTERFACE to the name of a variable of type PIMAGE_INTERFACE, will cause all calls generated to be called through this interface pointer.
ImageContains information about an image. The application has a limited knowledge of this structure detailing its position and size.
FontContains a font. The application has no knowledge of the content of this structure.
CDATA, COLORA color reference. CDATA is a flat uint32_t bit value, COLOR is an array of colors. Most routines use CDATA now, since color was difficult to actually use. They may still be converted to each other
PCDATAA pointer to a color (often as a 2 dimensional array of colors ie. An image surface.
PCOLORA very difficult value to use - a pointer to an array of bytes detailing color

Defines

Colors

Color macros are defined in <colordef.h>.
Color(r,g,b)Generates a CDATA value which has the specified color and level 255 alpha.
AColor(a,r,g,b)Generates a CDATA value which has the specified color and level specified level of alpha.
SetAlpha(rgb, a)Retains the color info portion of CDATA and replaces the alpha value.
RedVal(color)Fetches the red byte value of CDATA
BlueVal(color)Fetches the blue byte value of CDATA
GreenVal(color)Fetches the green byte value of CDATA
AlphaVal(color)Fetches the alpha byte value of CDATA
BASE_COLOR_BLACK Color( 0,0,0 )A color
BASE_COLOR_BLUE Color( 0, 0, 128 )A color
BASE_COLOR_GREEN Color( 0, 128, 0 )A color
BASE_COLOR_CYAN Color( 0, 128, 128 )A color
BASE_COLOR_RED Color( 192, 32, 32 )A color
BASE_COLOR_BROWN Color( 140, 0, 140 )A color
BASE_COLOR_MAGENTA Color( 160, 160, 0 )A color
BASE_COLOR_LIGHTGREY Color( 192, 192, 192 )A color
BASE_COLOR_DARKGREY Color( 128, 128, 128 )A color
BASE_COLOR_LIGHTBLUE Color( 0, 0, 255 )A color
BASE_COLOR_LIGHTGREEN Color( 0, 255, 0 )A color
BASE_COLOR_LIGHTCYAN Color( 0, 255, 255 )A color
BASE_COLOR_LIGHTRED Color( 255, 0, 0 )A color
BASE_COLOR_LIGHTMAGENTA Color( 255, 0, 255 )A color
BASE_COLOR_YELLOW Color( 255, 255, 0 )A color
BASE_COLOR_WHITE Color( 255, 255, 255 )A color

Alpha Values and Use

ALPHA_TRANSPARENT0x100Beginnging of use alpha channel. Any value more than this base will increase opacity up to completely solid.
ALPHA_TRANSPARENT_INVERT0x200Use Alpha channel. Any value more than this subtracts from the base opacity up to completely transparent.
ALPHA_TRANSPARENT_MAX 0x2FF more than this clips to total transparency for line, plot more than 255 will be total opaque... this max only applies to blotted images
Transparecy values and effects
0 no transparency - completely opaque
1
(TRUE)
0 value colors (absolute transparency) only
2-255
(0x02-0xff)
0 value color transparent, plus transparency factor applied to all
2 - mostly almost completely transparent
255 not transparent (opaque)
ALPHA_TRANSPARENT+n
(257-511)
(0x100-0x1ff)
alpha transparency in pixel plus transparency value - 256
0 value pixels will be transparent
257 - slightly more opaquen than the original
511 - image totally opaque - alpha will be totally overriden
no addition 511 nearly completely transparent
ALPHA_TRANSPARENT_INVERT+n
(512-767)
(0x200-0x2ff)
the low byte of this is subtracted from the alpha of the image this allows images to be more transparent than they were originally
512 - no modification alpha imge normal
600 - mid range... more transparent
767 - totally transparent
ALPHA_TRANSPARENT_MAX+
(768+)
(0x300+)
any value of transparent greater than the max will be clipped to max this will make very high values opaque totally...

Blot Methods
BLOT_COPYImage data is copied directly. No extra parameters required.
BLOT_SHADEDImage data is shaded according to one color. This works best for grey scale images, but can be applied to multi color images. One extra parameter is expected which is a CDATA type, only RGB components are used(?)
BLOT_MULTISHADEImage data is treated as 3 independant grey scale channels. Each channel is applied as a scalar to a color component. 3 CDATA type values are required when using this. The first is RED, second GREEN, third BLUE. These colors are scaled according to the appropriate (RGB) channel, and summed. This may seem like a silly thing to do, and I have yet to explain it to anyone such that it makes sense.

I usually use only 2 channels, one application used all 3. Suppose you have an image, a blue circle, and a green shade on it resembling a specular. The circle is entirely the same, uniform level of blue. The green specular is a varying shade of green. Together, the image looks like a blue circule with a semi-cyan specular - as each channel is indepenantly added together. Now, apply to the blue channel (which is for argument a constant 192) some other color. Scale this color between black and full intensity according to the blue channel. Pick this color as brown. Now the blue circle is brown, constant. Next, apply the green channel to some other color, say white. Now adding a white specular upon the brown circle causes a shiny stone like thing to be present. The circle color could easily be adjusted to red, blue, pink, brown, grey, and maintaining a white specular, which quickly uses one image to be many different colors (peices in a game?).

This may seem like a lot of work to do, but in actuality, doesn't cause as much overhead as one might expect, it's a rather simple operation to do, nearly approaching a simple shift and add.

Routines


PIMAGE_INTERFACE GetImageInterface( void )

Results in the pointer to the interface table for this library. Use of dynamic library load routines, and the request of this routine, makes for simple interfacing to the entire image library, and based on configuration may switch between libraries....

void DropImageInterface( void )

Release reference count of the library. There's normally not much in the way of cleanup that can be done. However, if image is being used as a service, then there is quite a bit of cleanup that needs to be done.

void SetBlotMethod( uint32_t method )

method is one of 3 values...
methods
BLOT_Cuse C routines for all operations.
BLOT_ASMuse assembly routines for operations which could take advantage of assembly.
BLOT_MMXuse MMX for computing alpha transparcy. Requires assembly.

If assembly was not available, the library will default to using C routines. These will always work, if slowly.


void SetStringBehavior( Image image, uint32_t method )

Unimplemented - intent....
methods
STRING_PRINT_RAW every character assumed to have a glyph-including '\0'
STRING_PRINT_CONTROL control characters perform 'typical' actions - newline, tab, backspace...
STRING_PRINT_C c style escape characters are handled \n \b \x# - literal text
STRING_PRINT_MENU & performs an underline, also does C style handling. \& == &
Each image has a default rendering mode. If NULL is specified as the image to set the method for, then this becomes the default string rendering mode for all images which don't otherwise specify.

CDATA ColorAverage( CDATA c1, CDATA c2, int d, int max)

Returns a color between c1 and c2. Max specifies the max range of d, and d is the marker inbetween which specifies how much of each color.
c1Color one.
c2Color two.
ddistance from 0 to max for the resulting color.
maxmaximum distance (resolution) of d

if d == 0, result is c1.
if d == max, result is c2.
else result is ( c1 * ( max - d ) + c2 * ( d ) ) / max

max = 2, d = 1, result exact average of colors.
max = 256, d = 64, result is 3/4 of c1 and 1/4 c2...

Image MakeImageFileEx( uint32_t width, uint32_t height DBG_PASS)

also referenced by these macros

MakeImageFile( width, height )

Creates an image. Width and height are unsigned values detailing how big to make the image. If either is 0, NULL image results, as an image which has no size is not an image.

Image MakeSubImageEx

( Image image

, int32_t x, int32_t y

, uint32_t width, uint32_t height

DBG_PASS)

also referenced by these macros

MakeSubImage( image, x, y, width, height )

Creates an image within an existing image. The position is specified with x, y; the size is specified with width, height. An image is allowed to be created such that it is beyond the bounds of the containing image. It may be larger, or positioned such that parts of it are beyond the parent. Any part of the sub image which is not within the parent is clipped to the parent.

Image LoadImageFileEx( char *name DBG_PASS)

also referenced by these macros

LoadImageFile( name )

Load an image from a file. Supported file type are bitmap(windows/os2), jpeg, PNG, GIF, (tiff/tga?). The content of the file is analyzed to determine the type of the image, so the name of the image does not matter. Gif images support single color transparency. PNG images will load an alpha channel if data is available. Most draw operations optionally treat any 0 color (black) as transparent, so a single color transparency may be created with bmp and jpeg images also. This however restricts the use of black, and therefore would need to be not quite black Color(0,0,1) for instance.

Image DecodeMemoryToImage( char *buf, uint32_t size )

If a buffer exists in memory which resembles loading a file off of a disk, this routine may be used to decode the image data into an image. LoadImageFile actually loads the image into a temporary buffer, and then calls this. buf is a pointer to the data to decode and size is the extent of the buffer.

Image UnmakeImageFileEx( Image image DBG_PASS )

also referenced by these macros

UnmakeImageFile(image )

Destroy an image. If sub images exist, the image is not entirely destroyed. Instead it is marked as destroyed, and once all sub images have been unmade, then the containing image is destroyed.

Image BuildImageFileEx( PCDATA pc, uint32_t width, uint32_t height DBG_PASS)

also referenced by these macros

BuildImageFile( pc, width, height )

If you have a buffer which you would wish to use for an image surface (which expects to have 32 bit ARGB color information). The specified buffer, width and height determine an image.

Image RemakeImageEx( Image image, PCDATA pc, uint32_t width, uint32_t height DBG_PASS )

also referenced by these macros

RemakeImage( image, pc, width, height )

Do a build image, but swap out the buffer, and redimension to specified width and height. An instance of this - under Windows, when the window is resized, the backed store DIB is resized, so that needs to be swapped out from the existing image which represents the window's surface.

void OrphanSubImage( Image image )

The specified image must be a sub-image, with a parent. The image is dis-related from its parent. It becomes a hidden image, with no surface, since it has lost a relationship to a master image's buffer.

void AdoptSubImage( Image foster, Image orphan )

The specified orphan must not have any parents. The orphan image is adopted by the foster image. The orphan's x, y position remain the same as before it was orphaned, unless modified in the meantime.

void SetImageBound( Image image, P_IMAGE_RECTANGLE bound )

This sets the region on an image which can be drawn into. Any operation beyond the bounds of the specified rectangle is clipped, and does not affect the image.

void FixImagePosition( Image image )

Resets any clipping boundries previously set.

void ResizeImageEx( Image image, int32_t width, int32_t height DBG_PASS )

also referenced by these macros

ResizeImage( image, width, height )

Modifies the size of an image to the specified width and height. If it is a top level image (has no parents), the buffer is resized. Any sub images are updated to this new surface.

void MoveImage( Image image, int32_t x, int32_t y )

This has no real effect on top level images. But for sub images, this will cause them to be relocated within their parent image.

void BlatColor

( Image image

, int32_t x, int32_t y

, uint32_t width, uint32_t height

, CDATA color )

void BlatAlphaColor

( Image image

, int32_t x, int32_t y

, uint32_t width, uint32_t height

, CDATA color )

also referenced by these macros

ClearImage( image )
ClearImageTo( image,color ) Sets the color of the specified rectangle to the specified color. The rectangle's position is set by x, y, and its extent by width, height. If Alpha version is used, then when the color is applied, it will be (probably) semi transparent, leaving what was already on the image, and shading the pixels to the current color.

ClearImage(image) is a macro which calls BlatColor( image, 0, 0, image.width, image.height, 0 ).

ClearImage(image,color) is a macro which calls BlatColor( image, 0, 0, image.width, image.height, color ).


void BlotImageEx

( Image dest

, Image src

, int32_t x, int32_t y

, uint32_t transparent

, uint32_t method, ... )

void BlotImageSizedEx

( Image dest

, Image src

, int32_t x, int32_t y

, int32_t xs, int32_t ys

, uint32_t width, uint32_t height

, uint32_t transparent

, uint32_t method, ... )

also referenced by these macros

copy blots
BlotImage( pd, ps, x, y )
BlotImageAlpha( pd, ps, x, y, a )
BlotImageSized( pd, ps, x, y, w, h )
BlotImageSizedTo( pd, ps, xd, yd, xs, ys, w, h )
shade blots
BlotImageShaded( pd, ps, x, y, c )
BlotImageShadedSized( pd, ps, xd, yd, xs, ys, w, h )
multi-shade blots
BlotImageMultiShaded( pd, ps, x, y, r, g, b )
BlotImageMultiShadedSized( pd, ps, xd, yd, xs, ys, w, h, r, g, b )

These routines copy one image (src) to another image (dest) without scaling. .
dest, pdDestination image
src, psSource image
x, yDestination coordinate
xd, ydDestination coordinate
xs, ysSource coordinate
w, hsize of area to copy
width, heightsize of area to copy
transparentHow to apply transparency effects. See table.
methodOptional parameters may follow. See table.
...optional parameters based on the BLOT_ mode. See table
aAlpha value to apply. See table.
ca single color - the shade parameter
rthe color to apply the red channel to
gthe color to apply the green channel to
bthe color to apply the blue channel to

void BlotScaledImageSizedEx

( Image pifDest, Image pifSrc

, int32_t xd, int32_t yd

, uint32_t wd, uint32_t hd

, int32_t xs, int32_t ys

, uint32_t ws, uint32_t hs

, uint32_t nTransparent

, uint32_t method, ... )

also referenced by these macros

copy blots
BlotScaledImageSized( pd, ps, xd, yd, wd, hd, xs, ys, ws, hs )
BlotScaledImageSizedTo( pd, ps, xd, yd, wd, hd)
BlotScaledImageSizedToAlpha( pd, ps, xd, yd, wd, hd, a)
BlotScaledImageAlpha( pd, ps, t )
BlotScaledImage( pd, ps )
BlotScaledImageTo( pd, ps )
shade blots
BlotScaledImageSizedToShaded( pd, ps, xd, yd, wd, hd, shade)
BlotScaledImageSizedToShadedAlpha( pd, ps, xd, yd, wd, hd, a, shade)
BlotScaledImageShadedAlpha( pd, ps, t, shade )
BlotScaledImageShaded( pd, ps, shade )
multi-shade blots
BlotScaledImageSizedToMultiShaded( pd, ps, xd, yd, wd, hd, t, r, g, b)
BlotScaledImageSizedToMultiShadedAlpha( pd, ps, xd, yd, wd, hd, a, r, g, b)
BlotScaledImageMultiShadedAlpha( pd, ps, t, r, g, b )
BlotScaledImageMultiShaded( pd, ps, r, g, b )

These routines copy one image (src) to another image (dest) scaled. .
pifDest; pdDestination image
pifSrc; psSource image
xd, ydDestination coordinate
wd, hdsize of area to copy to
xs, ysSource coordinate
ws, hssize of area to copy from
transparent; a; tHow to apply transparency effects. See table.
methodOptional parameters may follow. See table.
...optional parameters based on the BLOT_ mode. See table
c; shadea single color - the shade parameter
rthe color to apply the red channel to
gthe color to apply the green channel to
bthe color to apply the blue channel to

void plot( Image image, int32_t x, int32_t y, CDATA c)
void plotalpha( Image image, int32_t x, int32_t y, CDATA c)

Puts a pixel of color 'c' at (x, y) on 'image'. The color is stored exactly. If the alpha version is used, then the alpha channel on the pixel is applied to compute the resulting pixel based on prior content plus the new pixel.

CDATA getpixel( Image image, int32_t x, int32_t y )

Returns the pixel which is at (x, y) on image.

void do_line( Image image, int32_t x, int32_t y, int32_t xto, int32_t yto, CDATA color)
void do_lineAlpha( Image image, int32_t x, int32_t y, int32_t xto, int32_t yto, CDATA color)

Draws a line no more than 1 pixel thick from x, y to xto, yto. This is always done from top to bottom, and left to right. Reversing the coordinates results in the same line. If the Alpha version is used, the color is applied according to its alpha channel value. Otherwise, the color is literally set.

void do_hline( Image image, int32_t y, int32_t xfrom, int32_t xto, CDATA color )
void do_hlineAlpha( Image image, int32_t y, int32_t xfrom, int32_t xto, CDATA color )

Specialized line algorithm to do horizontal lines.

void do_vline( Image image, int32_t x, int32_t yfrom, int32_t yto, CDATA color )
void do_vlineAlpha( Image image, int32_t x, int32_t yfrom, int32_t yto, CDATA color )

Specialized line algorithm to do vertical lines.

Font GetDefaultFont( void )

Returns a handle which may be used for fonts. A font of NULL may also be passed to all functions which expect a font, in which case, this font handle is used.

uint32_t GetFontHeight( Font )

Returns the height of the font. This height member should be available for application reference in the Font structure?

uint32_t GetStringSizeFontEx( CTEXTSTR pString, uint32_t len, uint32_t *width, uint32_t *height, Font UseFont )

also referenced by these macros

GetStringSizeEx(s,len,pw,ph)
GetStringSize(s,pw,ph)
GetStringSizeFont(s,pw,ph,f)

Gets the size of a string of length. If Width is non NULL the width of the string is set into that variable. If height is non NULL the height of the string is set into that variable. The font to use to calculate for is passed as UseFont. The width of the string is returned. This should reference StringMethods... doesn't, especially since methods are per image and not global anymore.....
  • GetStringSizeEx - uses default font to calculate string size
  • GetStringSize - calls strlen() on the string passed, uses default font.
  • GetStringSizeFont - Calls strlen() on string passed, uses specified font.

  • uint32_t PutCharacterFont

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , unsigned char c, Font font );

    uint32_t PutCharacterInvertFont

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , unsigned char c, Font font );

    uint32_t PutCharacterVerticalFont

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , unsigned char c, Font font );

    uint32_t PutCharacterVerticalInvertFont

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , unsigned char c, Font font );

    also referenced by these macros

    PutCharacter(img,x,y,fore,back,c)
    PutCharacterVertical(img,x,y,fore,back,c)
    PutCharacterInvert(img,x,y,fore,back,c)
    PutCharacterInvertVertical(img,x,y,fore,back,c)

    Output a character, using the specifed font, or the default font. The background, if 0 RGB (alpha does not matter), then the background will not be output, only the character in foreground color.

    All of the macros use the default font (pass a NULL as font parameter).

    The (x,y) coordinate always references the top/left pixel of the character, if viewing the font in 'normal', 'right-side-up' orientation.

    Vertical modification draws the character 90 degrees clockwise rotated, using the x, y point to start from.

    Invert modification draws the character 180 degrees clockwise rotated, using the x, y point to start from.

    Invert and Vertical modifications draws the character 270 degrees clockwise rotated, using the x, y point to start from.

    The value returned is the width of the character, going along in a left-to right direction, assuming the first character is the 'left'.


    uint32_t PutStringFontEx

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , char *pc, uint32_t nLen

    , Font font )

    uint32_t PutStringVerticalFontEx

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , char *pc, uint32_t nLen

    , Font font )

    uint32_t PutStringInvertFontEx

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , char *pc, uint32_t nLen

    , Font font )

    uint32_t PutStringInvertVerticalFontEx

    ( Image pImage

    , int32_t x, int32_t y

    , CDATA color, CDATA background

    , char *pc, uint32_t nLen

    , Font font )

    also referenced by these macros

    PutString(pi,x,y,fore,back,pc)
    PutStringEx(pi,x,y,color,back,pc,len)
    PutStringFont(pi,x,y,fore,back,pc,font)
    PutStringVertical(pi,x,y,fore,back,pc)
    PutStringVerticalEx(pi,x,y,color,back,pc,len)
    PutStringVerticalFont(pi,x,y,fore,back,pc,font)
    PutStringInvert(pi,x,y,fore,back,pc)
    PutStringInvertEx(pi,x,y,color,back,pc,len)
    PutStringInvertFont(pi,x,y,fore,back,pc,font)
    PutStringInvertVertical(pi,x,y,fore,back,pc)
    PutStringInvertVerticalEx(pi,x,y,color,back,pc,len)
    PutStringInvertVerticalFont(pi,x,y,fore,back,pc,font)

    This outputs a string, using the (x,y) coordinate as the achor of the top left corner of the first character, assuming the character is aligned normally, upright.
  • Ex - denotes that the length of the string is also passed
  • Font - denotes that the font is specified
  • FontEx - Both the font and the length of the string are specified.
  • Vertical - Rotate 90 degrees clockwise around the (x,y) point is still the upper-left of the first character in normal orientation..
  • Invert - Rotate 180 degrees clockwise around the (x,y) point is still the upper-left of the first character in normal orientation..
  • InvertVertical - Rotate 270 degrees clockwise around the (x,y) point is still the upper-left of the first character in normal orientation..


  • uint32_t GetMaxStringLengthFont( int32_t width, Font font )

    Based on the average size of the font's characters, result in the maximum string length that may be shown in this width using this font.

    void GetImageSize( Image image, uint32_t* width, uint32_t* height )

    Results in the size of the image. Although this information is readily available by dereferencing the image pointer, this is the preferred way to get the information. However, due to the number of macros which reference for defaults the width and height, this has been left public information.

    PCDATA GetImageSurface( Image image )

    Returns the current surface buffer of an image. It could be used to get a memory mapped image of the buffer for direct use by a client(?).

    Font LoadFont( Font )

    Transfers a font to the server, and results in a font handle appropriate for use in further text operations.

    void UnloadFont( Font )

    A previously transferred font is unloaded from the server.

    void SyncImage( void )

    When used as a service, this makes sure that all outstanding image operations have completed, and then control is returned to the caller.

    int IntersectRectangle

    ( P_IMAGE_RECTANGLE result

    , P_IMAGE_RECTANGLE r1

    , P_IMAGE_RECTANGLE r2 )

    Result rectangle is the intersection of r1, r2. That is, it is the area which both rectangles have in common. Result is TRUE if there is something in result, otherwise the result is FALSE.

    int MergeRectangle

    ( P_IMAGE_RECTANGLE result

    , P_IMAGE_RECTANGLE r1

    , P_IMAGE_RECTANGLE r2 )

    Result rectangle is the union of r1, r2. That is, it is the area which includes both rectangles. This will often be substantially larger than either rectangle individually. Result is undefined.

    void GetImageAuxRect( Image image, P_IMAGE_RECTANGLE rect )

    Each image has a user rectangle associated with it. The display library uses this to keep information about partial image clipping. This routine gets the auxiliary rectangle.

    void SetImageAuxRect( Image image, P_IMAGE_RECTANGLE rect )

    Each image has a user rectangle associated with it. The display library uses this to keep information about partial image clipping. This routine sets the auxiliary rectangle.