Scrupp: Image handling

Image support is implemented using SDL_image.

JPEG support requires the JPEG library:: IJG Homepage
PNG support requires the PNG library:: PNG Homepage
and the Zlib library:: Zlib Homepage
TIFF support requires the TIFF library:: SGI TIFF FTP Site

Loading

scrupp.addImage(filename): Loads the image file with the given filename. Supported formats: BMP, PNM (PPM/PGM/PBM), XPM, LBM, PCX, GIF, JPEG, PNG and TIFF. Returns an image object.
scrupp.addImageFromString(str): Loads the image from the string str. Supports the same formats as scrupp.addImage(). Returns an image object.

Methods

image:getWidth(): Returns the image width.
image:getHeight(): Returns the image height.
image:getSize(): Returns the width and the height of the image.

image:isTransparent(x, y): Returns true if the pixel of the image with the coordinates x and y is not opaque, i.e. has an alpha value lower than 255. Returns false otherwise. This is not influenced by the alpha value of the whole image changed using image:setAlpha().

image:setAlpha(alpha): Changes the alpha value of the image. alpha has to be between 0 (transparent) and 255 (opaque).
image:getAlpha(): Returns the current alpha value of the image. This value is between 0 (transparent) and 255 (opaque).

image:setColor(r, g, b): Changes the color of the image. Think of this as a color filter so e.g. if you set it to red, only the red part of every pixel is rendered. r, g, b have to be numbers in the range from 0 to 255.
image:getColor(): Returns three numbers in the range from 0 to 255, one for each color component (r, g, b). If no color was set using image:setColor(r, g, b) white (255, 255, 255) is returned.
image:clearColor(): Removes any custom color from the image. After that it's like the color was white (255, 255, 255) so everything is rendered normally.

image:setCenterX(cx)
image:setCenterY(cy)
image:setCenter(cx, cy): These functions change the center of the image. The image is rendered with these coordinates at the position given to image:render(x, y). Furthermore, the image is rotated around this point. The default center of an image is (0, 0), the top left corner.
image:getCenterX()
image:getCenterY()
image:getCenter(): Returns the x-, the y- or both coordinates of the image's center.

image:setScaleX(sx)
image:setScaleY(sy)
image:setScale(sx, sy): These functions change the scaling of the image. The default scaling of an image is (1, 1), it's original size.
image:getScaleX()
image:getScaleY()
image:getScale(): Returns the x-, the y- or both scaling factors of the image.

image:setRotation(angle): Changes the rotation of the image. The angle in degrees defaults to 0. Positive angles rotate clockwise.
image:getRotation(): Returns the current rotation's angle of the image in degrees.

image:setRect(x, y, w, h): Changes the part of the image which should be rendered. You can define the top left corner of the rectangle (x, y) and the width and height (w, h).
image:getRect(): Returns four numbers (x, y, w, h) describing the part of the image which should be rendered. If no rectangle was set using image:setRect(x, y, w, h) (0, 0, width of image, height of image) is returned.
image:clearRect(): Removes any custom rectangle from the image. After that it's like the rectangle is (0, 0, width of image, height of image) so the whole image is rendered.

image:render(x, y): Renders the image at the window coordinates x and y.
image:render(table): This is nearly the same as the last one. This time a table contains the arguments. It's complete structure follows.
table = { x, -- x-coordinate of the image position -- mandatory y, -- y-coordinate of the image position -- mandatory centerX = [x-coordinate of the center for positioning, scaling and rotation], -- optional centerY = [y-coordinate of the center for positioning, scaling and rotation], -- optional scaleX = [scale factor for the x-axis], -- optional scaleY = [scale factor for the y-axis], -- optional rotate = [angle in degrees to rotate the image], -- optional rect = { x, y, width, height }, -- optional color = { red, green, blue, alpha } -- optional }
The first two elements of the array part of the table have to be the x- and y-coordinate of the point that the image should be rendered at. The table may have an optional rect entry. This has to be a table describing the rectangle the image should be clipped to. It contains the x- and y-coordinate of the top left corner and the width and height of the rectangle inside the image. The entries centerX and centerY are optional and default to zero, the top left corner of the image. scaleX and scaleY are optional as well and default to one. rotate has a default value of zero dregrees and is optional, too. The optional color entry is a table defining some kind of color filter. If you have a grayscale image, it will be colorized with this color. As always the table looks like this: {red, green, blue, [alpha]} with each value between 0 and 255. The default is opaque white, so the color of the image is not changed.

Example

scrupp.init("Image Test", 600, 400, 32, false)

-- load an image file
local image = scrupp.addImage("path_to_image_file")

-- get the dimension of the image
local width = image:getWidth()
local height = image:getHeight()

-- this has the same result:
local width, height = image:getSize()

if width > scrupp.getWindowWidth() or height > scrupp.getWindowHeight() then
	print("Please choose an image with smaller dimensions.")
	scrupp.exit()
end

-- calculate the x- and y-coordinate of the image
local x = (scrupp.getWindowWidth()-width)/2
local y = (scrupp.getWindowHeight()-height)/2

main = {
	render = function(dt)
		-- get the position of the mouse pointer
		mx, my = mouse:getPos()
		-- set the image alpha depending on the x-coordinate of the 
		-- mouse pointer
		image:setAlpha(mx/scrupp.getWindowWidth()*200+50)
		-- if you click with the left mouse button,
		-- only a part of the image is rendered
		if mouse.isDown("left") then
			image:render{
				mx, my,
				rect = { mx-x, my-y, width/2, height/2 }
			}
		-- otherwise the whole image is rendered
		else
			image:render(x,y)
		end
	end
}