Table of Contents
 
CreateImage
 

Purpose

creates a new, blank image surface object to blit to (or from)
 

Protoype

void CImageMngr::CreateImage (Uint32 ui_flags, string str_img_id, int i_width, int i_height, int i_depth, int i_xpos, 
                              int i_ypos, RGB_SET rgb_key = RGB_SET(), bool b_bound = false, bool b_visible = true)
 

Parameters

flags surface creation flags
img_id the unique ID of the new image object
width the width of the new image surface
height the height of the new image surface
depth the color bit depth of the new image surface (8, 16, 32)
xpos the X location of the image object on screen
ypos the Y location of the image object on screen
key the RGB transparency color key
bound whether the image is bound to another object (TRUE) or not (FALSE)
visible whether the image is visible (TRUE) or not (FALSE)
 

Description

This function is used to create a new surface object that can then be used by the game as a regular image object. The reason for using this function rather than AddImage() is that this function does not load an image from a file, it just creates a new, blank surface of certain specifications. It has many similarities to AddImage() however - you must pass in the new object's unique ID as well as having the option of setting its initial screen location. The width and height of the new surface dictate what can be displayed on it. Anything larger than the surface that is blitted on to it will not be totally displayed. In this was you can create a psuedo clip window by blitting a larger image onto a smaller surface.

Surface Flags

Since you are creating a new surface from scratch, you must define the properties of that surface. AddImage() does that for you when it loads in the image file, but here you are dealing with raw functionality. In most cases you can use the predefined flag combination of NEW_SURFACE to create the surface from. This enables hardware acceleration for the surface as well as color key transparency. If you need more, you can logically OR the following flags together to create surface properties. It's suggested that you OR them with NEW_SURFACE.

NOTE: All these flags are directly SDL-related and are not wrapped in any way. The table below comes straight from the SDL documentation.

SDL_SWSURFACE SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.
SDL_HWSURFACE SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video->Video blits (which are often accelerated). (used in NEW_SURFACE)
SDL_SRCCOLORKEY This flag turns on colourkeying for blits from this surface. If SDL_HWSURFACE is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory. (used in NEW_SURFACE)
SDL_SRCALPHA This flag turns on alpha-blending for blits from this surface. If SDL_HWSURFACE is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible.

Transparency

Image transparency is done with color keys. Since each image is assigned a color key, each image can have its own transparency color. The way color keys work is the key is stored as an RGB value. When an image with a color key is blitted to another surface, all pixels in the image that match the RGB key are not blitted, hence the transparency. Color keys are assigned as RGB_SET objects. Passing in a null RGB_SET will disable color-keying for that image.

Image Binding

This is simply whether or not this image object is going to be used (and thus rendered) by another manager class. For instance, an icon image is bound to a button object of CButtonMngr. CButtonMngr is the class that actually renders the image on the screen, not CImageMngr. However if an image is not bound to any other manager then CImageMngr will render it.
 

Use

CImageMngr image;
image.CreateImage(NEW_SURFACE, "my_image", 250, 250, 16, 0, 0, RGB_SET(255, 0, 255), false);
 
Prev: ClipImage
Next: DrawImage