Difference between revisions of "Legacy:Surface"

Revision as of 05:31, 4 June 2013

The Surface object is like an off-screen canvas on which you can draw and manipulate image data.

Initializers

• CreateSurface(width, height, color): Create a Surface of dimensions (width, height), filled with color.
• GrabSurface(x, y, width, height): Grab the screen contents at (x, y, width, height) and store it in a new Surface.
• Image.createSurface(): Create a new Surface using the picture data in the image.
• LoadSurface(filename): Create a Surface from an image given by filename.

Methods

• 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.
• 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
• Surface.createImage(): Create a new Image with the picture data in the surface.
• 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
• 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.

  BLEND (default for drawing)

  REPLACE

  RGB_ONLY

  ALPHA_ONLY

  ADD

  SUBTRACT

  MULTIPLY (default for masking)

  AVERAGE

  INVERT

• Surface.setAlpha(alpha): sets the alpha of the surface
• 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
• 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
• 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)
• 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
• 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.

Members

• width unsigned integer, read-only. Width of the surface in pixels.
• height unsigned integer, read-only. Height of the surface in pixels.

Notes

• It is faster to blit an image to screen than a surface, but it is much easier to manipulate a surface.
• The Surface object can be used to quickly make custom screenshots:
  

  GrabSurface(0, 0, GetScreenWidth(), GetScreenHeight()).save("my_screenshot.png");

• The fundamental pixel colors can be altered in any way using Surface.applyLookup(), or the Sphere ColorMatrix object functions Surface.applyColorFX() and Surface.applyColorFX4().

See also

• Sphere ColorMatrix object
• Sphere Image object

API:Surface/navbox