graphics package
License
The graphics package is marked as Compatible, which means any game can use it.
Classes
Frisket
A Frisket is a pure alpha channel with no color information of its own. It is usually used for text. See Drawable:BlitFrisket.
- frisket = SubCritical.Construct("Frisket", width, height)
- Creates a new, completely transparent frisket.
- destination:CopyFrisket(source, [source_x, source_y, source_w, source_h,] x, y)
- Copies data from source (a Frisket) to destination, with the top-left corner at x,y. If source_* are provided, deal with that subset of source.
- destination:ModulateFrisket(source, [source_x, source_y, source_w, source_h,] x, y)
- Multiplies the data from source (a Frisket) with the data already in destination, with the top-left corner at x,y. If source_* are provided, deal with that subset of source.
- destination:AddFrisket(source, [source_x, source_y, source_w, source_h,] x, y)
- Adds the data from source (a Frisket) to the data already in destination, with the top-left corner at x,y. If source_* are provided, deal with that subset of source.
- destination:SubtractFrisket(source, [source_x, source_y, source_w, source_h,] x, y)
- Subtracts the data in source (a Frisket) from the data already in destination, with the top-left corner at x,y. If source_* are provided, deal with that subset of source.
- destination:MinFrisket(source, [source_x, source_y, source_w, source_h,] x, y)
- Replace each frixel of destination with the frixels from source (a Frisket), but only if the new frixel is more transparent than the old one; with the top-left corner at x,y. If source_* are provided, deal with that subset of source.
- destination:MaxFrisket(source, [source_x, source_y, source_w, source_h,] x, y)
- Replace each frixel of destination with the frixels from source (a Frisket), but only if the new frixel is more opaque than the old one; with the top-left corner at x,y. If source_* are provided, deal with that subset of source.
- width,height = frisket:GetSize()
- Returns the pixel dimensions of this Frisket
- frisket:SetClipRect(x, y, width, height)
- Sets the clip rectangle of frisket. No frixels outside the clip rectangle will ever change.
- x, y, width, height = frisket:GetClipRect()
- Returns the clip rectangle of frisket.
- alpha = frisket:GetFrixel(x, y)
- Returns the alpha value at a given coordinate. This function is really slow.
- frixel = frisket:GetRawFrixel(x, y)
- Returns the raw frixel value (0-255) at a given coordinate. This function is really slow, but a little faster than GetFrixel.
Drawable
A Drawable is, basically, an image. It normally comes in two flavors, Graphic and GraphicsDevice. Both flavors support all of the below code.
- width,height = drawable:GetSize()
- Returns the pixel dimensions of this Drawable
- destination:Blit(source, [source_x, source_y, source_w, source_h,] x, y[, alpha])
- Draws source (a Drawable) on destination, with the top-left corner at x,y. If source_* are provided, deal with that subset of source. If alpha is specified, draw it with the given level of opacity. (1 is opaque, 0 is fully transparent.)
- Note: Unlike the corresponding function in SDL, this function handles partially-transparent blitting of an image with an alpha channel.
- Note 2: It is perfectly reasonable for source to be a GraphicsDevice.
- destination:BlitFrisket(source, [source_x, source_y, source_w, source_h,] x, y)
- Draws source (a Frisket) on destination, with the top-left corner at x,y. If source_* are provided, deal with that subset of source.
- This function uses the selected primitive color (see SetPrimitiveColor). If the primitive color is transparent, source's data is modulated appropriately.
- destination:Copy(source, [source_x, source_y, source_w, source_h,] x, y)
- Identical to Blit, but copies data (including alpha channel) without blending. Useful for composing/decomposing sprite sheets.
- Note: This is the only blitting operation that is permitted on a Drawable which has an alpha channel. This is also the only blitting operation that can cause a Drawable that previously had no alpha channel to have one, in which event the Drawable is now tainted and cannot be blitted on in any other way. This tainting will occur whenever you copy from a Drawable that has an alpha channel, regardless of whether you copied any of its transparent pixels!
- drawable:SetPrimitiveColor(r, g, b[, a])
- Sets the current "primitive color," which is used by DrawPoints, DrawLines, DrawLineLoop, DrawLineStrip, DrawTriangles, DrawTriangleStrip, DrawTriangleFan, DrawRect, DrawBox, and BlitFrisket. If a is not provided, full opacity (1) is assumed.
- drawable:SetPrimitiveColorPremul(pr, pg, pb[, a])
- Like above, but using premultiplied colors. If you don't understand what this means, use SetPrimitiveColor instead.
- Note that this will not work right with Friskets.
- destination:DrawPoints(coords, diameter)
- Draw points diameter in diameter at every coordinate in coords (a CoordArray, see CompileCoords) using the current primitive color.
- Note: Points, and all other primitives, fully support alpha in the primitive color.
- Note 2: Currently, points are rendered as rectangles and lack subpixel precision. In the future, they may be rendered as circles and gain subpixel precision.
- destination:DrawLines(coords, indices, width, [height])
- Each pair of indices in indices (an IndexArray, see CompileIndices) designates two coordinate pairs in coords (a CoordArray, see CompileCoords) between which a width (possibly non-integer) pixel wide line should be drawn using the current primitive color. (height should only be specified to handle non-1:1 aspect ratios.)
- Lines in SubCritical are drawn with subpixel precision, but not antialiased.
- If you wish to draw only a single line, the following code is more convenient:
local _i = SCUtil.CompileIndices{0,1}
function draw_line(destination, width, x1, y1, x2, y2)
local c = SCUtil.CompileCoords{x1,y1,x2,y2}
return destination:DrawLines(width, c, _i)
end- If you want to draw only straight horizontal or vertical lines, you should use DrawRect (or DrawBox) instead, since its results are easier to control. (DrawLine might disagree with your expectations on exactly what pixels get filled.)
- Note: Lines, and all other primitives, fully support alpha in the primitive color.
- destination:DrawLineStrip(coords, indices, width, [height])
- As with DrawLines, but indices are handled differently. The first index does nothing on its own. All indices after it designate a line between themselves and the index before them. (Essentially, indices designates a continuous strip of lines, hence the name.)
- destination:DrawLineLoop(coords, indices, width, [height])
- As with DrawLineStrip, with an additional line between the last and first indices.
- destination:DrawTriangles(coords, indices)
- Each triple of indices in indices (an IndexArray, see CompileIndices) designates three coordinate pairs in coords (a CoordArray, see CompileCoords) which form a triangle that should be drawn with the current primitive color.
- Triangles in SubCritical are drawn with subpixel precision, but not antialiased. SubCritical consistently uses a top-left fill convention, so abutting triangles will not have holes or overdraw. SubCritical also does clipping to the clip rectangle of the Drawable, so you gain nothing from doing such clipping yourself.
- Note: Triangles, and all other primitives, fully support alpha in the primitive color.
- destination:DrawTriangleStrip(coords, indices)
- As with DrawTriangles, but indices are handled differently. The first triple designates a triangle, then each index after that designates a new triangle between it and the two indices before it.
- destination:DrawTriangleFan(coords, indices)
- As with DrawTriangles, but indices are handled differently. The first triple designates a triangle, then each index after that designates a new triangle between it, the index before it, and the first index.
- destination:DrawRect(left, top, width, height)
- Designates a rectangle to be drawn in the primitive color. (This function's interface was changed as of 0b1.)
- destination:DrawBox(left, top, width, height) -- thickness of 1
destination:DrawBox(left, top, width, height, thickness)
- Designates a rectangle to be outlined in the primitive color at the given thickness. The lines will fall entirely inside the given rectangle.
- drawable:SetClipRect(x, y, width, height)
- Sets the clip rectangle of drawable. No pixels outside the clip rectangle will ever change.
- x, y, width, height = drawable:GetClipRect()
- Returns the clip rectangle of drawable.
- graphic = drawable:TakeSnapshot()
- A convenience function that returns a Graphic containing a copy of the current image data in drawable. No drawing state is copied, only image data.
- red, green, blue, alpha = drawable:GetPixel(x, y)
- Returns the color values at a given coordinate in a linear colorspace. This function is really slow.
- pixel = drawable:GetRawPixel(x, y)
- Returns the raw pixel value (0-4294967295 in ARGB8888 format) at a given coordinate. This function is really slow, but a little faster than GetPixel or GetSRGBPixel.
- alpha = drawable:GetRawAlpha(x, y)
- Returns the raw alpha value (0-255) at a given coordinate. This function is really slow, but a little faster than GetPixel or GetSRGBPixel.
- pixel = drawable:GetRawPixelNoAlpha(x, y)
- Returns the raw pixel value (0-16777215 in RGB888 format) with the alpha channel removed at a given coordinate. This function is really slow, but a little faster than GetPixel or GetSRGBPixel.
- red, green, blue, alpha = drawable:GetSRGBPixel(x, y)
- Returns the raw color values at a given coordinate in the sRGB colorspace. This function is really slow, but a little faster than GetPixel. sRGB color values are not suitable for direct use by other SubCritical functions accepting colors as parameters; if you intend to use these values elsewhere in SubCritical, you probably want GetPixel instead.
A Graphic is a Drawable whose lot in life is to eventually be blitted to other Drawables. See Drawable:Blit.
- graphic = SubCritical.Construct("Graphic", width, height)
- Creates a new graphic with no alpha channel (but undefined data).
- graphic:OptimizeFor(drawable)
- If necessary, converts graphic's internal pixel format for fast blitting to drawable. This is normally done automatically, but you can do the work ahead of time with this function if you so choose. (It's not worth it.)
GraphicsDevice : Drawable
A GraphicsDevice is a mild-mannered Drawable by day and what the user actually sees by night.
- device = SubCritical.Construct("GraphicsDevice", width, height)
device = SubCritical.Construct("GraphicsDevice", width, height, {[windowed=is_windowed,] [title=window_title,] [extensions]})
- Tries to construct and initialize a new GraphicsDevice of the given width and height. If windowed, try to create a windowed context instead of a fullscreen one. If windowed is not specified, and width and height are zero, pick a reasonable size (such as the user's current desktop resolution). If the exact resolution cannot be achieved, use black borders and the smallest resolution large enough to fit all the requested pixels. If title is specified, use window_title instead of the device-specific default title.
- A list of known extensions:
- true_width, true_height = some_width, some_height
- If specified, the GraphicsDevice will simulate a framebuffer of these dimensions, scaling up or down as needed for display. A retro-style game might set a true_width of 256 and a true_height of 224 for a Super Nintendo screen, for instance.
- keep_aspect = true
- If true, and a true_width and/or true_height are specified, black borders may be added to avoid "squishing" of the video. You probably want to specify this, especially if the display width and height are zero.
- smooth_filter = true
- If true, and a true_width and/or true_height are specified, try to use a smoother filter for magnification. If you are not dealing with a display width and height that are an integer multiple of the true_width and true_height, you probably want this.
- device:Update()
device:Update(x, y, width, height)
- Copies the pixels inside the given rectangle (or, if none is specified, all pixels) to the screen, where the user can get at them. A common mistake is to forget to call this after you're finished blitting.
- x,y = device:GetMousePos()
- Returns the current mouse position, in pixels.
- This should only be used if you need to know where the mouse is right now and someone else was handling events immediately prior.
- event = device:GetEvent{[wait=should_wait,] [relmouse=should_relmouse,] [textok=is_textok,]}
- If any events are available, return the next one as a table. If wait is true, don't return until an event becomes available. If relmouse is true, return relative mouse motion directly instead of keeping track of an absolute mouse position. If textok is true, process the user's keystrokes and give us every character they type.
- The returned table contains a "type" member denoting its type. Its structure is complicated. An example game included in this directory (printevents.scg) will print all received events, you can use it to determine the form of the specific events you're looking for.
GraphicLoader
An instance of GraphicLoader is poised to read from image files and give you nice, juicy Graphics to use in your game.
You cannot instantiate a GraphicLoader directly, and should not try to Construct one, since you won't know what formats the returned GraphicLoader can load. Instead, you should Construct a specific loader (such as PNGLoader) and use that.
- graphic = loader:Load(path)
graphic,othergraphic,... = loader:Load(path, otherpath, ...)
graphic = assert(loader:Load(path))
- Tries to load the graphic located at path (see SCPath) in a format this GraphicLoader understands. If this graphic is important, you may want to assert it (as shown above).
GraphicDumper
An instance of GraphicDumper is poised to save the contents of your Drawables in some wild new image format.
You cannot instantiate a GraphicDumper directly, and should not try to Construct one, since you won't know what format the returned GraphicDumper will save in. Instead, you should Construct a specific dumper (such as PNGDumper) and use that.
- function func(value, data) ... end
dumper:Dump(image, value, func)
- image is any Drawable, value is anything at all, and func is a function that will be called like func(value, data) where data is data to be written to the file. func must return true (or some other true value) if the write succeeded.
- It is an amazing coincidence that it just so happens that this is how file:write behaves. For some Lua file, then, one could dumper:Dump(image, file, file.write). Total coincidence, of course.
Utility functions
- coords = SCUtil.CompileCoords(table)
- Returns a CoordArray suitable for passing to many of Drawable's drawing functions. table should be an array directly containing coordinate pairs in the form of numbers, and in particular must not be an array of tables.
- indices = SCUtil.CompileIndices(table)
- Returns an IndexArray suitable for passing to many of Drawable's drawing functions. table should be an array directly containing 0-based indices in the form of numbers.
- new_indices = SCUtil.CullTrianglesCW(coords, indices)
new_indices = SCUtil.CullTrianglesCCW(coords, indices)
- Returns an IndexArray containing only those triangles described by coords and indices that wind in the specified direction (clockwise for CW and counter-clockwise for CCW).
Back to index