Xors3d Engine
Images

Functions

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

Function Documentation

BBDECL void BBCALL 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
BBDECL void BBCALL xImageAlpha ( Sprite *  image,
float  alpha 
)

Sets image alpha value.

Parameters:
imageImage handle
alphaAlpha value
BBDECL ImageBuffer* BBCALL 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
BBDECL Sprite* BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL xFreeImage ( Sprite *  image)

Frees up an image.

Parameters:
imageImage handle
BBDECL Sprite* BBCALL 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
BBDECL Sprite* BBCALL 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
BBDECL void BBCALL xSaveImage ( Sprite *  image,
const char *  path,
int  frame = 0 
)

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

Parameters:
imageImage handle
pathString with filename to save to
frameWhich frame of the image to save
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL float BBCALL xImageAngle ( Sprite *  image)

Returns the angle of an image.

Parameters:
imageImage handle
BBDECL int BBCALL xImageWidth ( Sprite *  image)

Returns the width of the given image in pixels.

Parameters:
imageImage handle
BBDECL int BBCALL xImageHeight ( Sprite *  image)

Returns the height of the given image in pixels.

Parameters:
imageImage handle
BBDECL int BBCALL 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
BBDECL int BBCALL 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
BBDECL int BBCALL 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
BBDECL int BBCALL xImageXHandle ( Sprite *  image)

Returns x location of an image's drawing handle.

Parameters:
imageImage handle
BBDECL int BBCALL xImageYHandle ( Sprite *  image)

Returns y location of an image's drawing handle.

Parameters:
imageImage handle
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL int BBCALL 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
BBDECL void BBCALL 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
BBDECL Sprite* BBCALL xCopyImage ( Sprite *  image)

Creates image's copy.

Parameters:
imageImage handle
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL int BBCALL xImageActualWidth ( Sprite *  image)

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

Parameters:
imageImage handle
BBDECL int BBCALL xImageActualHeight ( Sprite *  image)

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

Parameters:
imageImage handle