Although Sprite Candy image objects look exactly the same as common 2D-images, they are actually 3D objects (textured quads) and therefore provide great advantages, compared to their 2D-counterparts: you can rotate, resize, colorize, alpharize, skew them -or whatever- at highspeed.

Using Sprite Candy, you can put all images you need on a single texture, for example -so you only have to load this texture (image collection) once to display several different images. Placing several images together on a texture offers many advantages:

Resource_Handle% =  HUD_LoadImageResource (  textureFile$,  [mode%],  [maskR%],  [maskG%],  [maskB%]  )

Before you can create images, you must load a texture (image resource) and create a layer with it. This command will load a texture into memory and returns a unique texture handle that you will need with most image commands. You can also load common animation strips (as used with Blitz2D, for example). Since textures have to be square sized on most graphic cards, Sprite Candy will check the image size and adjust it automatically, when needed -without distorting the image's content. Once a texture has been loaded, it can be used on as many layers and as many times as you like to.

textureFile$
Path and file name of a texture that contains one or more images. Textures should be square sized and their width and height should be a power of 2 (32,64,128,256,512 or 1024, for example). Otherwise, Sprite Candy will correct the size of the image automatically.

textureMode%
Optional texture settings to be applied to the texture loaded:

Resource_Handle% =  HUD_LoadMemoryResource (  TextureHandle%,  [mode%],  [maskR%],  [maskG%],  [maskB%]  )

Whilst HUD_LoadImageResource loads a texture file from disk, you can also use dynamically created textures from memory.

TextureHandle%
Blitz handle of a texture in memory.

textureMode%
Sets the texture mode - you can either use the same texture mode you used to create the original texture, but also a different one since Sprite Candy creates a copy of this texture using this mode.

maskR% , maskG% , maskB%
Used with textureMode 4 only. You can optionally specify a mask color. All pixels using the specified RGB color will be masked (become transparent) then when using textureMode 4. If not specified, all black pixels will be masked by default.

Texture_Handle% =  HUD_GetTextureHandle (  Resource_Handle%  )

Sprite Candy commands like HUD_LoadImageResource or HUD_LoadFont do return internal Sprite Candy ID's, not Blitz texture handles. If you want to modify a texture directly, you can use this command to get the Blitz texture handle of a loaded image or font.

Resource_Handle%
The handle of an image resource loaded with HUD_LoadImageResource( ).

Image_Handle% =  HUD_CreateImage (  Layer_Handle%,  x%,  y%,  [clip_x%],  [clip_y%],  [clip_w%],  [clip_h%],  [xAlign$],  [yAlign$],  [zOrder%]  )

This command creates an images object on the specified layer, using the layer's texture. You can define the texture area that the image should display (start coordinates, width and height). If you do not specify a texture area, the complete texture will be shown.

Layer_Handle%
The handle of a layer, created with HUD_CreateLayer( ). The image object will use the layer's texture.

x% , y%
The screen x- and y-postion where the created image should be placed to, where x=0 is the left screen border and y=0 the topmost screen position. These parameters will be ignored, when xAlign$ or yAlign$ have been set (see below).

clip_x% , clip_y%
Defines the start position of the texture area that the image should display (in pixels). If you do not specify a texture area, the complete texture will be shown.

clip_w% , clip_h%
The width and height of the texture area to display (in pixels), counted from the start position. The created image will have the same size as the texture area it displays.

xAlign$

Image_Handle% =  HUD_CreateTiledImage (  Layer_Handle%,  x%,  y%,  [image_w%],  [image_h%],  [clip_x%],  [clip_y%],  [clip_w%],  [clip_h%],  [xAlign$],  [yAlign$],  [zOrder%]  )

This command creates a tiled image object on the specified layer, using the layer's texture. You can define the texture area that the image should display (start coordinates, width and height) and the width and height of the image itself. The texture area will be repeated to fill the entire image width and height then.

Layer_Handle%
The handle of a layer, created with HUD_CreateLayer( ). The image object will use the layer's texture.

x% , y%
The screen x- and y-postion, where the created image should be placed to, where x=0 is the left screen border and y=0 the topmost screen position. These parameters will be ignored, when xAlign$ or yAlign$ have been set (see below).

image_w% , image_h%
Defines the width and height of the image object (which should be higher than the width and height of the texture clip to display, of course). The defined texture clip will be repeated to fill the entire image width and height then.

clip_x% , clip_y%
Defines the start position of the texture area that the image should display (in pixels).

clip_w% , clip_h%
The width and height of the texture area to display (in pixels), counted from the start position. The created image will have the same size as the texture area it displays.

xAlign$

HUD_ChangeImageSize (  Image_Handle%,  width%,  height%  )

Changes the size (width and height) of an image object (tiled or normal one). If the object is a normal image, the texture area that the image displays will be resized, too. With a tiled image, the texture pattern will be repeated automatically to fill the entire image.

Image_Handle%
The handle of a image, created with HUD_CreateImage( ) or HUD_CreateTiledImage( ).

width% , height%
The desired width and height of the image, in pixels.

HUD_MirrorImage (  Image_Handle%,  TRUE | FALSE  )

This command mirrors an image horizontally.

state% =   HUD_IsMirrored (  Image_Handle%  )

This command returns TRUE if the specified image is currently mirrored, otherwise FALSE.

Image_Handle%
The handle of an image object.

HUD_FlipImage (  Image_Handle%,  TRUE | FALSE  )

This command flips an image vertically.

state% =   HUD_IsFlipped (  Image_Handle%  )

This command returns TRUE if the specified image is currently flipped, otherwise FALSE.

Image_Handle%
The handle of an image object.

HUD_SetImageClip (  Image_Handle%,  clip_x%,  clip_y%  )

This command will change the texture clip (area) that is displayed by an image, so it can be used to change an image's content without creating a new image. You can also animate images manually using this command by changing an images content frequently.

Image_Handle%
The handle of an image created with HUD_CreateImage( ) or HUD_CreateTiledImage( ).

clip_x% , clip_y%
These two parameters define the left x and y start position (in pixels) of the texture area to display.

HUD_MoveImageClip (  Image_Handle%,  step_x%,  step_y%  )

This command will move the current texture clip of an image object at a certain x / y amount (pixels).

Image_Handle%
The handle of an image created with HUD_CreateImage( ) or HUD_CreateTiledImage( ).

step_x% , step_y%
Specifies how many pixels the image's texture clip should be moved either to the left or right (x) or to the top or bottom (y).

x% | y% | width% | height% =   HUD_GetImageClip (  Image_Handle%,  value$%  )

Using this command you can retrieve information about an image's current texture clip position or size (the texture area that an image displays).

Image_Handle%
The handle of an image created with HUD_CreateImage( ) or HUD_CreateTiledImage( ).

value$

HUD_AnimateImage (  Image_Handle%,  startx%,  starty%,  framesTotal%,  framesPerRow%,  [mode$],  [loops%],  [speed%]  )

Images can be animated automatically without any additional work for you. This command defines an image's animation. The animation will be started immediately. You can also pause, resume and remove an image's animation at any time.

Sprite Candy images are animated by moving an image's texture clip stepwise from one texture position to the next. Therefore, all animation frames of an image must be placed as a block on the same texture (see sample image).

To animate an image automatically, Sprite Candy needs some information, such as: start position of the animation block on texture, size of a single frame (as with common Blitz animations, all frames must be of same size), the total number of frames and the number of frames in a single row (the last rows may contain less frames than the other rows). Sprite Candy will then automatically move the image's texture clip stepwise from left to right, until the end of a row, then move down a row, stepping again from left to right... and so on.

Image_Handle%
The handle of an image (or tiled image) created with HUD_CreateImage( ) or HUD_CreateTiledImage( ).

startx% , starty%
The x- and y-coordinate of the first frame's top-left corner on texture. The width and height of each animation frame will be determined by the image's current clip size.

framesTotal%
Specify the total number of frames here (counted from 1).

framesPerRow%
Indicate, how many frames are placed in a row. The last row may contain less images than the other rows.

mode$

HUD_SetAnimSpeed (  Image_Handle%,  speed%  )

Sets or changes the speed of an existing image animation -also while playing.

Image_Handle%
The handle of an animated image object. An image animation must have been defined for this image, using HUD_AnimateImage( ) before.

speed%
The duration (in milliseconds) for each animation frame.

HUD_SetAnimFrame (  Image_Handle%,  frame%,  [stop%]  )

This command displays a specified frame of an image animation. Automatic animation will be stopped, when currently active. Use this command to animate an image 'manually' or to display a specific frame on demand. Before using this command, you must first define the animation for the specified image, using HUD_AnimateImage( ).

Image_Handle%
The handle of an image object. An image animation must have been defined for this image, using HUD_AnimateImage( ) before.

frame%
The frame number to display (counted from 1).

stop%

frame% =  HUD_GetAnimFrame (  Image_Handle%  )

This command returns the currently displayed frame of an animated image. Before using this command, you must first define the animation for the specified image, using HUD_AnimateImage( ).

Image_Handle%
The handle of an (animated) image object.

HUD_SetAnimMode (  Image_Handle%,  mode$  )

Changes the animation mode of an existing image animation while playing.

Image_Handle%
The handle of an (animated) image object.

mode$

HUD_PauseImageAnimations (  [Image_Handle%]  )

This command pauses a running image animation at the currently displayed frame. The animation can be resumed at any time without re-defining the image's animation. If no object handle is specified, ALL image animations will be paused at once.

Image_Handle%
The handle of an image object. The specified image must be set to 'animated' using HUD_AnimateImage( ) before. If you do not specify an object handle, this command will affect ALL existing image animations at once.

HUD_PlayImageAnimations (  [Image_Handle%]  )

This command resumes a paused image animation from the currently displayed frame. If no object handle has been specified, ALL paused image animations will be resumed.

Image_Handle%
The handle of an image object. The specified image must be set to 'animated' using HUD_AnimateImage( ) before. If you do not specify an object handle, this command will affect ALL existing image animations at once.

HUD_ClearImageAnimations (  Image_Handle%  )

This command clears the defined animation (and all related parameters) of an animated HUD image. Use this command if you want to remove a previously defined image animation completely. After using this command, the animated image will treated like a normal static image again. The image itself will not be removed. If you want to animate it again, you will have to re-define it's animation using HUD_AnimateImage( ). If you want to stop an animation only and to restart it at a later time, you should use HUD_PauseImageAnimations( ) instead.

Image_Handle%
The handle of an image object. The specified image must be set to 'animated' using HUD_AnimateImage( ) before.