Apollolux: /* See also */ add category

2013-06-04T05:32:24Z

‎See also: add category

Apollolux: created from http://web.archive.org/web/20110801003448/http://www.spheredev.org/wiki/Object-Surface

2013-06-04T05:31:40Z

created from http://web.archive.org/web/20110801003448/http://www.spheredev.org/wiki/Object-Surface

New page

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

__TOC__

==Initializers==

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

==Methods==
* [[API:Surface/clone|Surface.clone]](): Create a copy of the surface object.
* [[API:Surface/cloneSection|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.
* [[API:Surface/blit|Surface.blit]](''x'', ''y''): Draw the surface on the screen at (''x'', ''y'').
* [[API:Surface/blitSurface|Surface.blitSurface]](surface, x, y): draws 'surface' onto 'surface_object' at (x,y)
* [[API:Surface/blitImage|Surface.blitImage]](''image_object'', ''x'', ''y''): draws 'image' onto 'surface_object' at (x,y)
* [[API:Surface/blitMaskSurface|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
* [[API:Surface/rotateBlitSurface|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
* [[API:Surface/rotateBlitMaskSurface|Surface.rotateBlitMaskSurface]](surface, x, y, angle, mask [, mask_blend_mode]): [[API:Surface/rotateBlitSurface|rotateBlitSurface]] + [[API:Surface/blitMaskSurface|blitMaskSurface]]
* [[API:Surface/zoomBlitSurface|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.
* [[API:Surface/zoomBlitMaskSurface|Surface.zoomBlitMaskSurface]](surface, x, y, factor, mask [, mask_blend_mode]): [[API:Surface/zoomBlitSurface|zoomBlitSurface]] + [[API:Surface/blitMaskSurface|blitMaskSurface]]
* [[API:Surface/transformBlitSurface|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.
* [[API:Surface/transformBlitMaskSurface|Surface.transformBlitMaskSurface]](surface, x1, y1, x2, y2, x3, y3, x4, y4, mask [, mask_blend_mode]): [[API:Surface/transformBlitSurface|transformBlitSurface]] + [[API:Surface/blitMaskSurface|blitMaskSurface]]
* [[API:Surface/createImage|Surface.createImage]](): Create a new [[API:Image|Image]] with the picture data in the surface.
* [[API:Surface/save|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
* [[API:Surface/setBlendMode|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
* [[API:Surface/setAlpha|Surface.setAlpha]](alpha): sets the alpha of the surface
* [[API:Surface/getPixel|Surface.getPixel]](''x'', ''y''): Get the color of the pixel at (''x'', ''y'') on the surface.
* [[API:Surface/setPixel|Surface.setPixel]](x, y, color): Set the pixel at (''x'', ''y'') on the surface to ''color''.
* [[API:Surface/replaceColor|Surface.replaceColor]](oldColor, newColor): replace all pixels of the color oldColor in the surface with newColor
* [[API:Surface/rotate|Surface.rotate]](''angle'', ''resize''): Rotate the surface by ''angle'' radians, ''resize'' to fit if requested.
* [[API:Surface/resize|Surface.resize]](w, h): resizes the surface images. This does not stretch or shrink the image inside the surface.
* [[API:Surface/rescale|Surface.rescale]](w, h): stretches or shrinks the surface to the new width w and height h
* [[API:Surface/flipHorizontally|Surface.flipHorizontally]](): flips the surface horizontally
* [[API:Surface/flipVertically|Surface.flipVertically]](): flips the surface vertically
* [[API:Surface/applyLookup|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: <code>var invert_lookup = [255, 254, 253, 252, 251, ..., 4, 3, 2, 1, 0];</code>
* [[API:Surface/applyColorFX|Surface.applyColorFX]](x, y, w, h, colormatrix): Apply the colormatrix to the pixels contained in x, y, w, h (see [[API:CreateColorMatrix|CreateColorMatrix]])
* [[API:Surface/applyColorFX4|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 [[API:CreateColorMatrix|CreateColorMatrix]])
* [[API:Surface/pointSeries|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)
* [[API:Surface/line|Surface.line]](''x1'', ''y1'', ''x2'', ''y2'', ''color''): Draw a line onto the surface starting from (''x1'', ''y1'') to (''x2'', ''y2'') with ''color''.
* [[API:Surface/gradientLine|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''.
* [[API:Surface/lineSeries|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)
* [[API:Surface/bezierCurve|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)
* [[API:Surface/outlinedRectangle|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.
* [[API:Surface/rectangle|Surface.rectangle]](''x1'', ''y1'', ''x2'', ''y2'', ''color''): Draw a filled rectangle on the surface from (''x1'', ''y1'') to (''x2'', ''y2'') with ''color''.
* [[API:Surface/gradientRectangle|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
* [[API:Surface/triangle|Surface.triangle]](''x1'', ''y1'', ''x2'', ''y2'', ''x3'', ''y3'', ''color''): Draw a filled triangle with points (''x1'', ''y1''), (''x2'', ''y2''), (''x3'', ''y3'') with ''color''.
* [[API:Surface/gradientTriangle|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
* [[API:Surface/polygon|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.
* [[API:Surface/outlinedEllipse|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
* [[API:Surface/filledEllipse|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
* [[API:Surface/outlinedCircle|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
* [[API:Surface/filledCircle|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
* [[API:Surface/gradientCircle|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
* [[API:Surface/drawText|Surface.drawText]](font, x, y, text): draws 'text' at x, y with the font onto the surface_object
* [[API:Surface/drawZoomedText|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
* [[API:Surface/drawTextBox|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 [[API:Font/drawTextBox|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:<br/><syntaxhighlight>GrabSurface(0, 0, GetScreenWidth(), GetScreenHeight()).save("my_screenshot.png");</syntaxhighlight>
* The fundamental pixel colors can be altered in any way using [[API:Surface/applyLookup|Surface.applyLookup]](), or the Sphere [[API:ColorMatrix|ColorMatrix]] object functions [[API:Surface/applyColorFX|Surface.applyColorFX]]() and [[API:Surface/applyColorFX4|Surface.applyColorFX4]]().

==See also==
* Sphere [[API:ColorMatrix|ColorMatrix]] object
* Sphere [[API:Image|Image]] object

{{API:Surface/navbox}}

← Older revision		Revision as of 05:32, 4 June 2013
Line 91:		Line 91:

	{{API:Surface/navbox}}		{{API:Surface/navbox}}
		+	[[Category:Objects]]

Legacy:Surface - Revision history

Apollolux: /* See also */ add category

Apollolux: created from http://web.archive.org/web/20110801003448/http://www.spheredev.org/wiki/Object-Surface