Murl Engine Lua Addon API  Version 1.0 beta
Murl.IVideoSurface

The video surface interface.

The video surface stores properties and pixel data of a graphic image. The video surface offers cloning of surfaces of different pixel format and size, copying rectangular regions from other video surfaces and applying matte colors.


Table members

Methods


Clone(pixelFormat)

Create a clone of the surface with a specified pixel format.

Murl.IVideoSurface Clone(Murl.IEnums.PixelFormat pixelFormat)

Parameters
pixelFormatThe pixel format of the new surface.
Returns
Murl.IVideoSurface The new surface or null if conversion is not available.

Clone(pixelSizeX, pixelSizeY, scaler, gamma)

Create a clone of the surface with a specified size. Scaling to different size is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8 and IEnums::PIXEL_FORMAT_R8_G8_B8 only.

Murl.IVideoSurface Clone(Integer pixelSizeX, Integer pixelSizeY, Murl.IVideoScaler scaler, Number gamma)

Parameters
pixelSizeXThe number of horizontal pixels of the new surface.
pixelSizeYThe number of vertical pixels of the new surface.
scalerPointer to a scaler object or null to scale using the BoxVideoScaler.
gammaThe gamma value used during cloning.
Returns
Murl.IVideoSurface The new surface or null if conversion is not available.

Clone(pixelFormat, pixelSizeX, pixelSizeY, scaler, gamma)

Create a clone of the surface with a specified pixel format and size. Scaling to different size is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8 and IEnums::PIXEL_FORMAT_R8_G8_B8 only.

Murl.IVideoSurface Clone(Murl.IEnums.PixelFormat pixelFormat, Integer pixelSizeX, Integer pixelSizeY, Murl.IVideoScaler scaler, Number gamma)

Parameters
pixelFormatThe pixel format of the new surface.
pixelSizeXThe number of horizontal pixels of the new surface.
pixelSizeYThe number of vertical pixels of the new surface.
scalerPointer to a scaler object or null to scale using the BoxVideoScaler.
gammaThe gamma value used during cloning.
Returns
Murl.IVideoSurface The new surface or null if conversion is not available.

CloneRotated(orientation)

Create a clone of the surface with a specified orientation.

Murl.IVideoSurface CloneRotated(Murl.IEnums.Orientation orientation)

Parameters
orientationThe orientation of the new surface.
Returns
Murl.IVideoSurface The new surface or null if conversion is not available.

CloneRotated(orientation, pixelFormat)

Create a clone of the surface with a specified orientation and pixel format.

Murl.IVideoSurface CloneRotated(Murl.IEnums.Orientation orientation, Murl.IEnums.PixelFormat pixelFormat)

Parameters
orientationThe orientation of the new surface.
pixelFormatThe pixel format of the new surface.
Returns
Murl.IVideoSurface The new surface or null if conversion is not available.

CloneFrame(positionX, positionY, pixelSizeX, pixelSizeY)

Create a surface and copy a specified rectangular region.

Murl.IVideoSurface CloneFrame(Integer positionX, Integer positionY, Integer pixelSizeX, Integer pixelSizeY)

Parameters
positionXThe source x-position of the region.
positionYThe source y-position of the region.
pixelSizeXThe number of horizontal pixels of the region.
pixelSizeYThe number of vertical pixels of the region.
Returns
Murl.IVideoSurface The new surface with the specified region's size.

GetPixelSizeX()

Get the number of horizontal pixels.

Integer GetPixelSizeX()

Returns
Integer The number of horizontal pixels.

GetPixelSizeY()

Get the number of vertical pixels.

Integer GetPixelSizeY()

Returns
Integer The number of vertical pixels.

GetBytesPerLine()

Get the number of bytes per line.

Integer GetBytesPerLine()

Returns
Integer The number of bytes per line.

GetBytesPerPixel()

Get the number of bytes per pixel.

Integer GetBytesPerPixel()

Returns
Integer The number of bytes per pixel.

GetPixelFormat()

Get the pixel format of the surface.

Murl.IEnums.PixelFormat GetPixelFormat()

Returns
Murl.IEnums.PixelFormat The pixel format of the surface.

GetPixels()

Get the data object which is holding the pixels.

Murl.ConstData GetPixels()

Returns
Murl.ConstData The data object which is holding the pixels.

GetMutablePixels()

Get the mutable data object which is holding the pixels.

Murl.MutableData GetMutablePixels()

Returns
Murl.MutableData The mutable data object which is holding the pixels.

GetPixel(positionX, positionY)

Get the color of a pixel.

Murl.Color GetPixel(Integer positionX, Integer positionY)

Parameters
positionXThe pixel x-position.
positionYThe pixel y-position.
Returns
Murl.Color The color of the pixel at the specified position.

SetPixel(positionX, positionY, color)

Set the color of a pixel.

Boolean SetPixel(Integer positionX, Integer positionY, Murl.Color color)

Parameters
positionXThe pixel x-position.
positionYThe pixel y-position.
colorThe color of the pixel to set.
Returns
Boolean true if successful.

FlipX()

Horizontally flip the surface.

Boolean FlipX()

Returns
Boolean true if successful.

FlipY()

Vertically flip the surface.

Boolean FlipY()

Returns
Boolean true if successful.

Blit(source, destPositionX, destPositionY)

Copy a source surface to a specified position. All cases of overlapping are supported.

Boolean Blit(Murl.IVideoSurface source, Integer destPositionX, Integer destPositionY)

Parameters
sourceThe source surface.
destPositionXThe destination x-position.
destPositionYThe destination y-position.
Returns
Boolean true if successful.

Blit(source, sourcePositionX, sourcePositionY, destPositionX, destPositionY, pixelSizeX, pixelSizeY)

Copy a rectangular region from a source surface to a specified position. All cases of overlapping are supported.

Boolean Blit(Murl.IVideoSurface source, Integer sourcePositionX, Integer sourcePositionY, Integer destPositionX, Integer destPositionY, Integer pixelSizeX, Integer pixelSizeY)

Parameters
sourceThe source surface.
sourcePositionXThe source x-position.
sourcePositionYThe source y-position.
destPositionXThe destination x-position.
destPositionYThe destination y-position.
pixelSizeXThe number of horizontal pixels to copy.
pixelSizeYThe number of vertical pixels to copy.
Returns
Boolean true if successful.

BlitScaled(source, scaler, gamma)

Copy a source surface of different size. Scaling to different size is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8 and IEnums::PIXEL_FORMAT_R8_G8_B8 only.

Boolean BlitScaled(Murl.IVideoSurface source, Murl.IVideoScaler scaler, Number gamma)

Parameters
sourceThe source surface.
scalerPointer to a scaler object or null to scale using the BoxVideoScaler.
gammaThe gamma value used during scaling.
Returns
Boolean true if successful.

Clear(positionX, positionY, pixelSizeX, pixelSizeY, clearColor)

Clear a rectangular region of the surface.

Boolean Clear(Integer positionX, Integer positionY, Integer pixelSizeX, Integer pixelSizeY, Murl.Color clearColor)

Parameters
positionXThe source x-position of the region.
positionYThe source y-position of the region.
pixelSizeXThe number of horizontal pixels of the region.
pixelSizeYThe number of vertical pixels of the region.
clearColorThe clear color to apply.
Returns
Boolean true if successful.

Clear(clearColor)

Clear the surface.

Boolean Clear(Murl.Color clearColor)

Parameters
clearColorThe clear color to apply.
Returns
Boolean true if successful.

GaussBlur(strength)

Perform a Gauss blur operation on the surface.

Boolean GaussBlur(Number strength)

Parameters
strengthThe blur filter strength.
Returns
Boolean true if successful.

GaussBlur(positionX, positionY, pixelSizeX, pixelSizeY, strength)

Perform a Gauss blur operation on the surface.

Boolean GaussBlur(Integer positionX, Integer positionY, Integer pixelSizeX, Integer pixelSizeY, Number strength)

Parameters
positionXThe x-position of the region.
positionYThe y-position of the region.
pixelSizeXThe number of horizontal pixels of the region.
pixelSizeYThe number of vertical pixels of the region.
strengthThe blur filter strength.
Returns
Boolean true if successful.

Dither(redBits, greenBits, blueBits, alphaBits)

Apply Floyd-Steinberg dithering on the surface. The given bit counts represent the actual number of significant integer bits for each color component. For floating-point formats, the given normalized component value is first multiplied by 255.

Boolean Dither(Integer redBits, Integer greenBits, Integer blueBits, Integer alphaBits)

Parameters
redBitsThe number of significant bits for the red component.
greenBitsThe number of significant bits for the green component.
blueBitsThe number of significant bits for the blue component.
alphaBitsThe number of significant bits for the alpha component.
Returns
Boolean true if successful.

Dither(positionX, positionY, pixelSizeX, pixelSizeY, redBits, greenBits, blueBits, alphaBits)

Apply Floyd-Steinberg dithering on the surface. The given bit counts represent the actual number of significant integer bits for each color component. For floating-point formats, the given normalized component value is first multiplied by 255.

Boolean Dither(Integer positionX, Integer positionY, Integer pixelSizeX, Integer pixelSizeY, Integer redBits, Integer greenBits, Integer blueBits, Integer alphaBits)

Parameters
positionXThe x-position of the region.
positionYThe y-position of the region.
pixelSizeXThe number of horizontal pixels of the region.
pixelSizeYThe number of vertical pixels of the region.
redBitsThe number of significant bits for the red component.
greenBitsThe number of significant bits for the green component.
blueBitsThe number of significant bits for the blue component.
alphaBitsThe number of significant bits for the alpha component.
Returns
Boolean true if successful.

ApplyMatteFringe(matteFringe, matteThreshold)

Apply a matte fringe using a specified alpha threshold value. This operation affects all pixels whose alpha value is below or equal the given threshold. For these pixels, an average color value is calculated from all pixels within X/Y distance of "matteFringe" with alpha also nonzero. Applying matte fringe is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8, IEnums::PIXEL_FORMAT_L8_A8 and IEnums::PIXEL_FORMAT_R5_G5_B5_A1 only.

Boolean ApplyMatteFringe(Integer matteFringe, Number matteThreshold)

Parameters
matteFringeThe matte fringe size to apply.
matteThresholdThe alpha threshold in range [0.0 .. 1.0].
Returns
Boolean true if successful.

ApplyMatteFringe(positionX, positionY, pixelSizeX, pixelSizeY, matteFringe, matteThreshold)

Apply a matte color to a rectangular region using a specified alpha threshold value. This operation affects all pixels whose alpha value is below or equal the given threshold. For these pixels, an average color value is calculated from all pixels within X/Y distance of "matteFringe" with alpha also nonzero. Applying matte fringe is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8, IEnums::PIXEL_FORMAT_L8_A8 and IEnums::PIXEL_FORMAT_R5_G5_B5_A1 only.

Boolean ApplyMatteFringe(Integer positionX, Integer positionY, Integer pixelSizeX, Integer pixelSizeY, Integer matteFringe, Number matteThreshold)

Parameters
positionXThe source x-position of the region.
positionYThe source y-position of the region.
pixelSizeXThe number of horizontal pixels of the region.
pixelSizeYThe number of vertical pixels of the region.
matteFringeThe matte fringe size to apply.
matteThresholdThe alpha threshold in range [0.0 .. 1.0].
Returns
Boolean true if successful.

ApplyMatteColor(positionX, positionY, pixelSizeX, pixelSizeY, matteColor, matteThreshold)

Apply a matte color to a rectangular region using a specified alpha threshold value. The matte color's RGB values are set to all pixels which alpha values are less or equal to the specified alpha threshold value. Applying matte color is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8, IEnums::PIXEL_FORMAT_L8_A8 and IEnums::PIXEL_FORMAT_R5_G5_B5_A1 only.

Boolean ApplyMatteColor(Integer positionX, Integer positionY, Integer pixelSizeX, Integer pixelSizeY, Murl.Color matteColor, Number matteThreshold)

Parameters
positionXThe source x-position of the region.
positionYThe source y-position of the region.
pixelSizeXThe number of horizontal pixels of the region.
pixelSizeYThe number of vertical pixels of the region.
matteColorThe matte color to apply.
matteThresholdThe alpha threshold in range [0.0 .. 1.0].
Returns
Boolean true if successful.

ApplyMatteColor(matteColor, matteThreshold)

Apply a matte color using a specified alpha threshold value. The matte color's RGB values are set to all pixels which alpha values are less or equal to the specified alpha threshold value. Applying matte color is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8, IEnums::PIXEL_FORMAT_L8_A8 and IEnums::PIXEL_FORMAT_R5_G5_B5_A1 only.

Boolean ApplyMatteColor(Murl.Color matteColor, Number matteThreshold)

Parameters
matteColorThe matte color to apply.
matteThresholdThe alpha threshold in range [0.0 .. 1.0].
Returns
Boolean true if successful.

RenderText(font, text, textColor, backgroundColor, clearSurface, enableWordWrap, containerPosX, containerPosY, containerSizeX, containerSizeY, alignX, alignY)

Render some text into the surface using a given font.

Boolean RenderText(Murl.IFont font, String text, Murl.Color textColor, Murl.Color backgroundColor, Boolean clearSurface, Boolean enableWordWrap, Number containerPosX, Number containerPosY, Number containerSizeX, Number containerSizeY, Murl.IEnums.TextAlignmentX alignX, Murl.IEnums.TextAlignmentY alignY)

Parameters
fontThe font used for rendering.
textThe text to render.
textColorThe text color to render.
backgroundColorThe text background color to render.
clearSurfaceIf true, the output surface is cleared before rendering.
enableWordWrapIf true, word wrapping is enabled.
containerPosXThe horizontal text position in the video stream.
containerPosYThe vertical text position in the video stream.
containerSizeXThe horizontal size of the text rectangle, or 0 if the video stream's X size should be used
containerSizeYThe vertical size of the text rectangle, or 0 if the video stream's Y size should be used
alignXThe horizontal text alignment.
alignYThe vertical text alignment.
Returns
Boolean true if successful.

IsColumnEmpty(column, threshold)

Check if a column is empty using a specified alpha threshold value. Checking is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8 and IEnums::PIXEL_FORMAT_R5_G5_B5_A1 only.

Boolean IsColumnEmpty(Integer column, Number threshold)

Parameters
columnThe zero-based column.
thresholdThe alpha threshold in range [0.0 .. 1.0].
Returns
Boolean true if all alpha values in the column are less or equal to the threshold.

IsRowEmpty(row, threshold)

Check if a row is empty using a specified alpha threshold value. Checking is supported for IEnums::PIXEL_FORMAT_R8_G8_B8_A8 and IEnums::PIXEL_FORMAT_R5_G5_B5_A1 only.

Boolean IsRowEmpty(Integer row, Number threshold)

Parameters
rowThe zero-based row.
thresholdThe alpha threshold in range [0.0 .. 1.0].
Returns
Boolean true if all alpha values in the row are less or equal to the threshold.

ClipSizeXRight(positionX, sizeX)

Clip the width relative to a position and the right border of the surface.

Integer ClipSizeXRight(Integer positionX, Integer sizeX)

Parameters
positionXThe x-position.
sizeXThe number of horzontal pixels.
Returns
Integer The clipped width.

ClipSizeYBottom(positionY, sizeY)

Clip the height relative to a position and the bottom border of the surface.

Integer ClipSizeYBottom(Integer positionY, Integer sizeY)

Parameters
positionYThe y-position.
sizeYThe number of vertical pixels.
Returns
Integer The clipped height.

Evict()

Evict restoreable resoures. Evictable surfaces can free resources e.g. on memory low warnings. These resources can be restored later by calling Restore().

Boolean Evict()

Returns
Boolean true if successful.

Restore()

Restore evictable resoures freed by Evict().

Boolean Restore()

Returns
Boolean true if successful.