Difference between revisions of "Legacy:Functions/Surfaces"

Revision as of 17:34, 22 May 2013

Surfaces

• CreateSurface(width, height, color): Create a Surface of dimensions (width, height), filled with color.

• LoadSurface(filename): Create a Surface from an image given by filename.

• GrabSurface(x, y, width, height): Grab the screen contents at (x, y, width, height) and store it in a new Surface.

Surface object

• Sphere Surface object: A picture canvas in memory that can be drawn to.

• Surface.setAlpha(alpha): sets the alpha of the surface
• Surface.clone(): Create a copy of the surface object.
• Surface.cloneSection(x, y, w, h): returns a new surface object with the height and width of h and w, with part of image at (x,y) from the surface_object with the width w and height h.

Drawing on surfaces

• Blend Modes
  • BLEND (default for drawing)
  • REPLACE
  • RGB_ONLY
  • ALPHA_ONLY
  • ADD
  • SUBTRACT
  • MULTIPLY (default for masking)
  • AVERAGE
  • INVERT

• Surface.setBlendMode(mode): Sets the blend mode of the surface, which will affect any drawing operation on the surface. 'mode' must be one of the available blend modes for surfaces.

• Surface.getPixel(x, y): Get the color of the pixel at (x, y) on the surface.
• Surface.setPixel(x, y, color): Set the pixel at (x, y) on the surface to color.
• Surface.replaceColor(oldColor, newColor): replace all pixels of the color oldColor in the surface with newColor

Primitives on surfaces

• Surface.pointSeries(array, color): plots a series of points colored with color onto the surface with array filled with objects (each object must have a 'x' and 'y' property)
• Surface.line(x1, y1, x2, y2, color): Draw a line onto the surface starting from (x1, y1) to (x2, y2) with color.
• Surface.gradientLine(x1, y1, x2, y2, color1, color2): Draw a line onto the surface starting from (x1, y1) to (x2, y2) with a color fade from color1 to color2.
• Surface.lineSeries(array, color [, type]): draws a series of lines colored with color onto the surface with array filled with objects (each object must have a 'x' and 'y' property)
• Surface.bezierCurve(color, step, Ax, Ay, Bx, By, Cx, Cy [, Dx] [, Dy]): Draws a Bezier curve colored with color onto the surface with step being a floating point number in the range 0 < step <= 1.0 and the points:

  (Ax, Ay: coordinates of the endpoint A),

  (Bx, By: coordinates of A's control point B)

  (Cx, Cy: coordinates of the endpoint C)

  (Dx, Dy: optional, coordinates of C's control point D - if omitted, B is also C's control point)

• Surface.outlinedRectangle(x, y, width, height, color [, size]): Draw an outlined rectangle onto the surface at (x, y) of width and height colored with color and with size determining the thickness.
• Surface.rectangle(x1, y1, x2, y2, color): Draw a filled rectangle on the surface from (x1, y1) to (x2, y2) with color.
• Surface.gradientRectangle(x, y, w, h, c_ul, c_ur, c_lr, c_ll): Draws a gradient rectangle onto the surface at (x,y) with the height h and width w and a gradient of colors graduating from each corner of the rectangle as follows:

  c_ul = color of upper left corner

  c_ur = color of upper right corner

  c_lr = color of lower right corner

  c_ll = color of lower left corner

• Surface.triangle(x1, y1, x2, y2, x3, y3, color): Draw a filled triangle with points (x1, y1), (x2, y2), (x3, y3) with color.
• Surface.gradientTriangle(x1, y1, x2, y2, x3, y3, c1, c2, c3): Draws a gradient triangle onto the surface with the points (x1, y1), (x2, y2), (x3, y3), with each point (c1 = color of (x1, y1), c2 = color of (x2, y2), c3 = color of (x3, y3)) having a color to generate the gradient of the triangle
• Surface.polygon(array, color [, invert]): draws a filled polygon colored with color onto the surface with array filled with objects (each object must have a 'x' and 'y' property)

  If invert is true, all points in the bounding box of the polygon, but not in the polygon will be colored.

• Surface.outlinedEllipse(x, y, rx, ry, c): Draws an outlined ellipse at (x, y) with rx being the horizontal radius and ry the vertical radius onto the surface with the color c
• Surface.filledEllipse(x, y, rx, ry, c): Draws a filled ellipse at (x, y) with rx being the horizontal radius and ry the vertical radius onto the surface with the color c
• Surface.outlinedCircle(x, y, radius, color [, antialias]): Draws an outlined circle at (x, y) colored with color onto the surface if antialias is true, the circle will be antialiased
• Surface.filledCircle(x, y, radius, color [, antialias]): Draws a filled circle at (x, y) colored with color onto the surface if antialias is true, the circle will be antialiased
• Surface.gradientCircle(x, y, radius, color1, color2 [, antialias]): Draws a gradient circle at (x, y) onto the surface colored with a fading color from color1 to color2 if antialias is true, the circle will be antialiased

Text on surfaces

• Surface.drawText(font, x, y, text): draws 'text' at x, y with the font onto the surface_object
• Surface.drawZoomedText(font, x, y, scale, text): draws scaled text (1.0 = normal) with (x,y) as the upper left corner onto the surface_object
• Surface.drawTextBox(font, x, y, w, h, offset, text): draws a word-wrapped text at (x, y) onto the surface_object with the width w and height h. The offset is the number of pixels which the number of pixels from y which the actual drawing starts at. See Font.drawTextBox for more detail.

Manipulating surfaces

• Surface.rotate(angle, resize): Rotate the surface by angle radians, resize to fit if requested.
• Surface.resize(w, h): resizes the surface images. This does not stretch or shrink the image inside the surface.
• Surface.rescale(w, h): stretches or shrinks the surface to the new width w and height h
• Surface.flipHorizontally(): flips the surface horizontally
• Surface.flipVertically(): flips the surface vertically

Color effects

• Surface.applyLookup(x, y, w, h, red_lookup, green_lookup, blue_lookup, alpha_lookup): Apply a lookup table transformation to the pixels contained in x, y, w, h

  The lookup parameters are arrays of 256 elements containg the new pixel values, ex: var invert_lookup = [255, 254, 253, 252, 251, ..., 4, 3, 2, 1, 0];

• Surface.applyColorFX(x, y, w, h, colormatrix): Apply the colormatrix to the pixels contained in x, y, w, h (see CreateColorMatrix)
• Surface.applyColorFX4(x, y, w, h, cm_upperleft, cm_upperright, cm_lowerleft, cm_lowerright): Apply 4 color matrices. Each corner has a separate color matrix. (see CreateColorMatrix)

Drawing (blitting) surfaces

• Surface.blit(x, y): Draw the surface on the screen at (x, y).
• Surface.blitSurface(surface, x, y): draws 'surface' onto 'surface_object' at (x,y)
• Surface.blitImage(image_object, x, y): draws 'image' onto 'surface_object' at (x,y)
• Surface.blitMaskSurface(surface, x, y, mask [, mask_blend_mode]): draws 'surface' onto the surface_object at (x, y), except that the color passed as 'mask' tints 'surface'; optionally you can pass one of the blend modes for masking as mask_blend_mode
• Surface.rotateBlitSurface(surface, x, y, angle): draws 'surface' onto the surface_object at (x, y), except that 'surface' is rotated anti-clockwise in radians, with -2*PI <= angle <= 2*PI
• Surface.rotateBlitMaskSurface(surface, x, y, angle, mask [, mask_blend_mode]): rotateBlitSurface + blitMaskSurface
• Surface.zoomBlitSurface(surface, x, y, factor): draws 'surface' onto the surface_object at (x, y) with zooming, with the scaling depending on factor. Normally a factor of 1 will draw a normal looking 'surface' and between 0 and 1 will shrink it. Any values greater than 1 will stretch it's size.
• Surface.zoomBlitMaskSurface(surface, x, y, factor, mask [, mask_blend_mode]): zoomBlitSurface + blitMaskSurface
• Surface.transformBlitSurface(surface, x1, y1, x2, y2, x3, y3, x4, y4): draws 'surface' onto the surface_object with "transformation", where (x1, y1) is the upper left corner, (x2, y2) the upper right corner, (x3, y3) is the lower right corner, and (x4, y4) is the lower left corner.
• Surface.transformBlitMaskSurface(surface, x1, y1, x2, y2, x3, y3, x4, y4, mask [, mask_blend_mode]): transformBlitSurface + blitMaskSurface

Conversion to image

• Surface.createImage(): Create a new Image with the picture data in the surface.

Saving to disk

• Surface.save(filename): saves the surface_object as an image using the filename 'filename'; the image type is determined by the extension of the file, e.g. surface.save("test.png") saves a png image called test.png