ifDraw2D

Coordinates (x,y) for this interface are based on an origin (0,0) at the top, left. (This is common for 2D drawing APIs, but is different than OpenGL's default coordinate system). Bitmap pixel values and color values are always represented as 32-bit integer RGBA color values. That is, red is in the most significant byte and alpha is in the least significant byte.

Starting in Roku OS 16.0, the Clear(), DrawLine(), DrawPoint(), and DrawRect() functions return a Boolean indicating whether the draw succeeded, as DrawObject() and its derivatives and DrawText() already did. When a draw fails, the reason is printed to the BrightScript debug log.

A bitmap must not be modified after it has been used as the source of another draw. Calling SwapBuffers() on the screen resets this state, after which the bitmap may be modified again.

Not allowed

offscreen.DrawLine(...)
screen.DrawObject(offscreen, ...)
' This DrawRect() will fail and return false in the future.
' In Roku OS 16.0, it returns true and prints a warning to the debug console.
offscreen.DrawRect(...)
screen.SwapBuffers()

Allowed

offscreen1.DrawLine(...)
offscreen2.DrawObject(offscreen1, ...)
screen.DrawObject(offscreen2, ...)
screen.SwapBuffers()      ' resets object state
offscreen1.DrawRect(...)  ' allowed
offscreen2.DrawLine(...)  ' allowed

Modifying a bitmap after it has been drawn to the screen but before SwapBuffers() is called returns true and the draw succeeds. The Roku debug console prints a warning that the app needs to be updated, because this will fail in a future release (Roku OS 16.3 at the earliest).

Implemented by

Supported methods

Clear(rgba as Integer) as Boolean

Description

Clears the bitmap, and fills it with the specified RGBA color.

The alpha channel will be filled into the bitmap, even when not used. Once AlphaEnable is set to true, the alpha channel will be taken into account when using this bitmap as a source. See SetAlphaEnable() for more information on alpha blending.

Parameters

Return Value

A flag indicating whether the bitmap was successfully cleared.

Clear() is not the same as a DrawRect() for the entire bitmap. Clear() fills the bitmap with the specified RGBA; it does not perform any alpha blending operations.

GetWidth() as Integer

Description

Gets the width of the bitmap.

Return Value

The width of the bitmap in pixels.

GetHeight() as Integer

Description

Gets the height of the bitmap in pixels.

Return Value

The height of the bitmap in pixels.

GetByteArray(x as Integer, y as Integer, width as Integer, height as Integer) as Object

Description

Gets the RGBA pixel values for the specified rectangle.

Parameters

Return Value

An roByteArray representing the RGBA pixel values for the specified rectangle.

GetPng(x as Integer, y as Integer, width as Integer, height as Integer) as Object

Description

Gets PNG image data for the specified area of the bitmap. The PNG is in 32-bit RGBA format.

Parameters

Return Value

An roByteArray object containing PNG image data for the specified area of the bitmap. If the coordinates are out of bounds, or the PNG conversion fails for any reason, then invalid is returned

Example

function SaveTestPng()
    w = 200 : h = 100
    bm = CreateObject("roBitmap", {width: w, height: h, AlphaEnable: true})
    bm.DrawRect(10, 10, w-20, h-20, &hFF0000FF)
    bm.Finish()
    ba = bm.GetPng(0, 0, w, h)
    ba.WriteFile("tmp:/test.png")
 end function

GetAlphaEnable() as Boolean

Description

Checks if the alpha blending is enabled.

Return Value

A flag indicating whether alpha blending is enabled.

SetAlphaEnable(enable as Boolean) as Void

Description

Enables alpha blending when the source bitmap is the destination. The setting of the source bitmap's alpha enable is ignored.

When alpha blending is enabled, each pixel in the destination bitmap is set by combining the destination and source pixels according to the alpha value in the source bitmap (or rectangle). The destination alpha is not used. (In OpenGL this is referred to as GL_ONE_MINUS_SRC_ALPHA).

By default, alpha blending is off. Even when alpha blending is off, the alpha value is still present in the bitmap, and it must be passed when a function parameter is a color, which is always RGBA.

Parameters

Example

function Main()
    s=CreateObject("roScreen")
    ' Clear to White with alpha fully opaque
    ' but alpha not actually ever used since it is the bottom most plane
    ' alpha is only looked at on "source" planes, not "destination".
    s.Clear(&hFFFFFFFF)

    ' AlphaEnable must be enabled in the destination surface to have effect.
    s.SetAlphaEnable(true)
    bm=CreateObject("roBitmap", {width:100, height: 100, alphaenable: false} )
    bm.Clear(&h0000FFFF) 'blue, fully opaque alpha

    ' draw a blue rect in the upper left corner
    s.DrawObject(0,0, bm)
    s.Finish()
    Sleep(2000)
    s.Clear(&hFFFFFFFF)
    bm.Clear(&h0000FF00) 'blue, fully transparent alpha

    ' draw a blue rect in the upper left corner
    ' but, since it is transparent, nothing will appear on the screen.
    s.DrawObject(0, 0, bm)
    s.Finish()
    Sleep(2000)
 end function

DrawRect(x as Integer, y as Integer, width as Integer, height as Integer, rgba as Integer) as Boolean

Description

Fills the specified rectangle from left (x), top (y) to right (x + width), bottom (y + height) with the RGBA color.

Parameters

Return Value

A flag indicating whether the rectangle was successfully drawn.

DrawPoint(x as Integer, y as Integer, size as Float, rgba as Integer) as Boolean

Description

Draws a point at (x,y) with the given size and RGBA color.

Parameters

Return Value

A flag indicating whether the point was successfully drawn.

DrawLine(xStart as Integer, yStart as Integer, xEnd as Integer, yEnd as Integer, rgba as Integer) as Boolean

Description

Draws a line from (xStart, yStart) to (xEnd, yEnd) with RGBA color.

Parameters

Return Value

A flag indicating whether the line was successfully drawn.

DrawObject(x as Integer, y as Integer, src as Object) as Boolean

Description

Draws the source object, where src is an roBitmap or an roRegion object, at position x,y.

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

DrawScaledObject(x as Integer, y as Integer, scaleX as Float, scaleY as Float, src as Object) as Boolean

Description

Draws the source object, where src is an roBitmap or an roRegion object, at position x,y, scaled in the x direction by scaleX and in the y direction by scaleY. scaleX and scaleY should each be greater than zero and less than one to reduce the object size, or greater than one to increase the object size

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

DrawScaledObject(x as Integer, y as Integer, scaleX as Float, scaleY as Float, src as Object, rgba as Integer) as Boolean

Description

Draws the source object, where src is an roBitmap or an roRegion object, at position x,y, scaled in the x direction by scaleX and in the y direction by scaleY. scaleX and scaleY should each be greater than zero and less than one to reduce the object size, or greater than one to increase the object size.

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

DrawRotatedObject(x as Integer, y as Integer, theta as Float, src as Object) as Boolean

Description

Draws the source object, where src is an roBitmap or an roRegion object, at position x,y rotated by angle theta degrees.

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

DrawTransformedObject(x as Integer, y as Integer, theta as Float, scaleX as Float, scaleY as Float, src as Object) as Boolean

Description

Draws and then scales and rotates the source object, where src is an roBitmap or an roRegion object; at position x,y; scaled in the x direction by scaleX and in the y direction by scaleY; and rotated by angle theta degrees.

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

DrawTransformedObject(x as Integer, y as Integer, theta as Float, scaleX as Float, scaleY as Float, src as Object, rgba as Integer) as Boolean

Description

Draws and then scales and rotates the source object, where src is an roBitmap or an roRegion object; at position x,y; scaled in the x direction by scaleX and in the y direction by scaleY; and rotated by angle theta degrees.

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

DrawRotatedObject(x as Integer, y as Integer, theta as Float, src as Object, rgba as Integer) as Boolean

Description

Draws and rotates the source object, where src is an roBitmap or an roRegion object at position x,y, rotated by angle theta degrees.

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

DrawText(text as String, x as Integer, y as Integer, rgba as Integer, font as Object) as Boolean

Description

Draws the text at position (x,y) using the specified RGBA color and roFont font object. Text is drawn anti-aliased. The background image/color behind the text will show through the spaces and holes in the text. To have the text erase the background, make a call to DrawRect() before calling DrawText(). The size, bold, and italic attributes are specified when creating the roFont.

Parameters

Return Value

A flag indicating whether the object was successfully drawn.

Finish() as Void

Description

Realizes the bitmap by finishing all queued draw calls. Until Finish() is called, prior graphics operations may not be user visible. For example, they may be in the graphics display pipeline, or in a server queue.

This method is synchronous; it does not return until all graphic operations are complete.

When working with an roScreen object, the ifScreen.SwapBuffers() method should be used instead of this method.