Xors3d Engine
Images

Functions

void xAutoMidHandle (int state)
 Enables or disables auto appling xMidhandle() for all loading images.
Sprite * xCopyImage (Sprite *image)
 Creates image's copy.
Sprite * xCreateImage (int width, int height, int frame=1)
 Creates a new image with a single frame or multiple frames for animation.
void xDrawBlock (Sprite *image, float x, float y, int frame=0)
 Draws a previously loaded image without transparent blocks.
void xDrawBlockRect (Sprite *image, float x, float y, float rectx, float recty, float rectWidth, float rectHeight, int frame=0)
 Draws a rectangular portion of an image to the designated location on the screen without transparent blocks.
void xDrawImage (Sprite *image, float x, float y, int frame=0)
 Draws a previously loaded image.
void xDrawImageRect (Sprite *image, float x, float y, float rectx, float recty, float rectWidth, float rectHeight, int frame=0)
 Draws a rectangular portion of an image to the designated location on the screen.
void xFreeImage (Sprite *image)
 Frees up an image.
void xGrabImage (Sprite *image, int x, int y, int frame=0)
 Grabs a portion of the current drawing buffer and stick it into an image.
void xHandleImage (Sprite *image, float x, float y)
 Sets image drawing handle position.
int xImageActualHeight (Sprite *image)
 Returns the height of the given image in pixels (images scale is taken into account).
int xImageActualWidth (Sprite *image)
 Returns the width of the given image in pixels (images scale is taken into account).
void xImageAlpha (Sprite *image, float alpha)
 Sets image alpha value.
float xImageAngle (Sprite *image)
 Returns the angle of an image.
ImageBuffer * xImageBuffer (Sprite *image, int frame=0)
 Returns specified image buffer handle.
void xImageColor (Sprite *image, int red, int green, int blue)
 Sets image rendering color.
int xImageHeight (Sprite *image)
 Returns the height of the given image in pixels.
int xImageRectCollide (Sprite *image, int x, int y, int frame, int rectx, int recty, int rectWidth, int rectHeight)
 Checks if image is collided with a rectangle on the screen.
int xImageRectOverlap (Sprite *image, float x, float y, float rectx, float recty, float rectWidth, float rectHeight)
 Checks if image is overlapped with a rectangle on the screen.
int xImagesCollide (Sprite *image1, int x1, int y1, int frame1, Sprite *image2, int x2, int y2, int frame2)
 Checks if images are collided.
int xImagesOverlap (Sprite *image1, float x1, float y1, Sprite *image2, float x2, float y2)
 Checks if images are overlapped.
int xImageWidth (Sprite *image)
 Returns the width of the given image in pixels.
int xImageXHandle (Sprite *image)
 Returns x location of an image's drawing handle.
int xImageYHandle (Sprite *image)
 Returns y location of an image's drawing handle.
Sprite * xLoadAnimImage (const char *path, int width, int height, int startFrame, int frames)
 Load's and animated image.
Sprite * xLoadImage (const char *path)
 This command loads an image.
void xMaskImage (Sprite *image, int red, int green, int blue)
 Sets image transparent color.
void xMidHandle (Sprite *image)
 Centers image drawing handle.
void xResizeImage (Sprite *image, float width, float height)
 Resizes an image to a new size using a values in pixels.
void xRotateImage (Sprite *image, float angle)
 Rotates images.
void xSaveImage (Sprite *image, const char *path, int frame=0)
 Saves an image or one of its frames to hard drive.
void xScaleImage (Sprite *image, float x, float y)
 Resizes an image to a new size using a floating point percentage.
void xTileImage (Sprite *image, float x, float y, int frame=0)
 Tiles image on the screen.

Function Documentation

void xImageColor ( Sprite *  image,
int  red,
int  green,
int  blue 
)

Sets image rendering color.

Parameters:
imageImage handle
redRed value of image rendering color
greenGreen value of image rendering color
blueBlue value of image rendering color
void xImageAlpha ( Sprite *  image,
float  alpha 
)

Sets image alpha value.

Parameters:
imageImage handle
alphaAlpha value
ImageBuffer* xImageBuffer ( Sprite *  image,
int  frame = 0 
)

Returns specified image buffer handle.

You may use it for directly drawing into image

Parameters:
imageImage handle
frameFrame of animated image
Sprite* xCreateImage ( int  width,
int  height,
int  frame = 1 
)

Creates a new image with a single frame or multiple frames for animation.

Parameters:
widthWidth of the new image
heightHeight of the new image
frameNumber of frames
void xGrabImage ( Sprite *  image,
int  x,
int  y,
int  frame = 0 
)

Grabs a portion of the current drawing buffer and stick it into an image.

Parameters:
imageImage handle
xStarting x location to grab
yStarting y location to grab
frameFrame to insert the grabbed image into
void xFreeImage ( Sprite *  image)

Frees up an image.

Parameters:
imageImage handle
Sprite* xLoadImage ( const char *  path)

This command loads an image.

You will use the xDrawImage() command to display the graphic later.

Parameters:
pathString containing filename of imge file
Sprite* xLoadAnimImage ( const char *  path,
int  width,
int  height,
int  startFrame,
int  frames 
)

Load's and animated image.

While similar to xLoadImage(), the xLoadAnimImage() loads a single image that is made up of 'frames' of seperate images (presumably to be used as frames of a graphic animation). The imagestrip itself consists of 2 or more frames, arranged in a single graphic image. There is no spaces between the frames, and each frame must be the same width and height. When loaded, the frames will be indexed in a left-to-right, top-to-bottom fashion, starting in the top left corner. When drawing the image to the screen with the xDrawImage() command, you specify which frame to draw with the frame parameter. To actually make your image animate, you'll need to cycle through the frames (like a flip book, cartoon, or any other video) quickly to give the illusion of motion. Our example will show you how to use one of the sample imagestrips and make it animate. While it may seem confusing, we are going to do some timer work as well as a little weird math.

Parameters:
pathString designating full path and filename to image
widthWidth in pixels of each frame in the image
heightHeight in pixels of each frame in the image
startFrameThe frame to start with (usually 0)
framesHow many frames you are using of the imagestrip
void xSaveImage ( Sprite *  image,
const char *  path,
int  frame = 0 
)

Saves an image or one of its frames to hard drive.

The image can be saved in BMP, PNG, JPG, DDS, TGA depending on the file extension.

Parameters:
imageImage handle
pathString with filename to save to
frameWhich frame of the image to save
void xDrawImage ( Sprite *  image,
float  x,
float  y,
int  frame = 0 
)

Draws a previously loaded image.

This command draws both single image graphics (loaded with the xLoadImage() command) as well as animated images (loaded with the xLoadAnimImage() command). You specify where on the screen you wish the image to appear. You can actually 'draw' off the screen as well by using negative values or positive values that are not visible 'on the screen'. Finally, if you are using an animated image (loaded with the xLoadAnimImage()), you can specify which frame of the imagestrip is displayed with the xDrawImage() command.

Parameters:
imageImage handle
xThe x location of the screen to display the image
yThe y location of the screen to display the image
frameThe frame number of the animated image to display
void xDrawImageRect ( Sprite *  image,
float  x,
float  y,
float  rectx,
float  recty,
float  rectWidth,
float  rectHeight,
int  frame = 0 
)

Draws a rectangular portion of an image to the designated location on the screen.

The transparent/masked portions of the original image will be drawn transparent, just as you normally would draw an image.

Parameters:
imageImage handle
xx location on the screen to draw the image
yy location on the screen to draw the image
rectxStarting x location within the image to draw
rectyStarting y location within the image to draw
rectWidthWidth of the area to draw
rectHeightHeight of the area to draw
frameFrame number of image to draw
void xScaleImage ( Sprite *  image,
float  x,
float  y 
)

Resizes an image to a new size using a floating point percentage.

Using a negative value perform image flipping. You may use this in realtime.

Parameters:
imageImage handle
xThe amount to scale the image horizontally
yThe amount to scale the image vertically
void xResizeImage ( Sprite *  image,
float  width,
float  height 
)

Resizes an image to a new size using a values in pixels.

Parameters:
imageImage handle
widthNew image width
heightNew image height
void xRotateImage ( Sprite *  image,
float  angle 
)

Rotates images.

The purpose of this command is to rotate an image a specified number of degrees. You my use it in realtime.

Parameters:
imageImage handle
angleFloating number from 0 to 360 degrees
float xImageAngle ( Sprite *  image)

Returns the angle of an image.

Parameters:
imageImage handle
int xImageWidth ( Sprite *  image)

Returns the width of the given image in pixels.

Parameters:
imageImage handle
int xImageHeight ( Sprite *  image)

Returns the height of the given image in pixels.

Parameters:
imageImage handle
int xImagesCollide ( Sprite *  image1,
int  x1,
int  y1,
int  frame1,
Sprite *  image2,
int  x2,
int  y2,
int  frame2 
)

Checks if images are collided.

This is the command to get pixel-perfect collisions between images. It will not consider transparent pixels during the collision check (basically, only the 'meat' of the image will invoke a collision). This makes it perfect for most situations where you have odd-shaped graphics to text against. The xImagesOverlap() command is mesh faster, however, but can only determine if any of the two images have overlapped (this includes transparent pixels). This method works if you have graphics that completely fill their container and/or you don't plan on needing pinpoint accuracy.

Parameters:
image1First image handle
x1First image x location
y1First image y location
frame1First image frame
image2Second image handle
x2Second image x location
y2Second image y location
frame2Second image frame
int xImageRectCollide ( Sprite *  image,
int  x,
int  y,
int  frame,
int  rectx,
int  recty,
int  rectWidth,
int  rectHeight 
)

Checks if image is collided with a rectangle on the screen.

There are many times when you need to see if an image has collided with (or is touching) a specific rectangular area of the screen. This command performs pixel perfect accurate collision detection between the image of your choice and a specified rectangle on the screen. Howevever, should your program just need to detect a graphic (like a mouse pointer) over at a particular location/region of the screen (often called a 'hot spot'), this command works great. As with any collision, you will need to know the PRECISE location of the graphic you wish to test collision with, as well as the x, y, width, and height of the screen area (rect) you wish to test.

Parameters:
imageImage handle
xImage's x location
yImage's y location
frameImage's frame
rectxx location start of the rect
rectyy location start of the rect
rectWidthWidth of the rect
rectHeightHeight of the rect
int xImageRectOverlap ( Sprite *  image,
float  x,
float  y,
float  rectx,
float  recty,
float  rectWidth,
float  rectHeight 
)

Checks if image is overlapped with a rectangle on the screen.

Parameters:
imageImage handle
xImage's x location
yImage's y location
rectxx location start of the rect
rectyy location start of the rect
rectWidthWidth of the rect
rectHeightHeight of the rect
int xImageXHandle ( Sprite *  image)

Returns x location of an image's drawing handle.

Parameters:
imageImage handle
int xImageYHandle ( Sprite *  image)

Returns y location of an image's drawing handle.

Parameters:
imageImage handle
void xHandleImage ( Sprite *  image,
float  x,
float  y 
)

Sets image drawing handle position.

When an image is loaded with xLoadImage(), the image handle (the location within the image where the image is 'drawn from') is always defaulted to the top left corner (coordinates 0, 0). This means if you draw an image that is 50x50 pixels at screen location 200, 200, the image will begin to be drawn at 200, 200 and extend to 250, 250. This command moves the image handle from the 0, 0 coordinate of the image to the specified x and y location in the image. You can retrieve an image's current location handle using the xImageXHandle() and xImageYHandle(). Finally, you can make all images automatically load with the image handle set to middle using the xAutoMidHandle() command.

Parameters:
imageImage handle
xx coordinate of the new image drawing handle location
yy coordinate of the new image drawing handle location
void xMidHandle ( Sprite *  image)

Centers image drawing handle.

When an image is loaded with xLoadImage(), the image handle (the location within the image where the image is 'drawn from') is always defaulted to the top left corner (coordinates 0, 0). This means if you draw an image that is 50x50 pixels at screen location 200, 200, the image will begin to be drawn at 200, 200 and extend to 250, 250. This command moves the image handle from the 0, 0 coordinate of the image to the exact middle of the image. Therefore, in the same scenario above, if you were to draw a 50x50 pixel image at screen location 200, 200 with its image handle set to Mid with this command, the image would start drawing at 175, 175 and extend to 225, 225. You can manual set the location of the image's handle using the xHandleImage() command. You can retrieve an image's handle using the xImageXHandle() and xImageYHandle(). Finally, you can make all images automatically load with the image handle set to middle using the xAutoMidHandle() command.

Parameters:
imageImage handle
void xAutoMidHandle ( int  state)

Enables or disables auto appling xMidhandle() for all loading images.

When an image is loaded with xLoadImage(), the image handle (the location within the image where the image is 'drawn from') is always defaulted to the top left corner (coordinates 0, 0). This means if you draw an image that is 50x50 pixels at screen location (200, 200), the image will begin to be drawn at (200, 200) and extend to (250, 250). The xMidHandle() command moves the image's handle to the middle of the image. See this command for more information about the image's handle. This command eliminates the need for the xMidHandle() command by making ALL subsequently loaded images default to having their image handles set to mid.

Parameters:
stateIf true - images will load with auto midhandle, without if false
void xTileImage ( Sprite *  image,
float  x,
float  y,
int  frame = 0 
)

Tiles image on the screen.

Parameters:
imageImage handle
xStarting x location of the tile
yStarting y location of the tile
frameImage frame
int xImagesOverlap ( Sprite *  image1,
float  x1,
float  y1,
Sprite *  image2,
float  x2,
float  y2 
)

Checks if images are overlapped.

This is a very fast, simple collision type command that will allow you to determine whether or not two images have overlapped each other. This does not take into account any transparent pixels (see xImagesCollide()). In many cases, you might be able to get away with using this more crude, yet quite fast method of collision detection. For games where your graphics are very squared off and pixel-perfect accuracy isn't a must, you can employ this command to do quick and dirty overlap checking.

Parameters:
image1First image handle
x1First image x location
y1First image y location
image2Second image handle
x2Second image x location
y2Second image y location
void xMaskImage ( Sprite *  image,
int  red,
int  green,
int  blue 
)

Sets image transparent color.

Parameters:
imageImage handle
redRed value of transparent color
greenGreen value of transparent color
blueBlue value of transparent color
Sprite* xCopyImage ( Sprite *  image)

Creates image's copy.

Parameters:
imageImage handle
void xDrawBlock ( Sprite *  image,
float  x,
float  y,
int  frame = 0 
)

Draws a previously loaded image without transparent blocks.

Parameters:
imageImage handle
xThe x location of the screen to display the image
yThe y location of the screen to display the image
frameThe frame number of the animated image to display
void xDrawBlockRect ( Sprite *  image,
float  x,
float  y,
float  rectx,
float  recty,
float  rectWidth,
float  rectHeight,
int  frame = 0 
)

Draws a rectangular portion of an image to the designated location on the screen without transparent blocks.

Parameters:
imageImage handle
xx location on the screen to draw the image
yy location on the screen to draw the image
rectxStarting x location within the image to draw
rectyStarting y location within the image to draw
rectWidthWidth of the area to draw
rectHeightHeight of the area to draw
frameFrame number of image to draw
int xImageActualWidth ( Sprite *  image)

Returns the width of the given image in pixels (images scale is taken into account).

Parameters:
imageImage handle
int xImageActualHeight ( Sprite *  image)

Returns the height of the given image in pixels (images scale is taken into account).

Parameters:
imageImage handle