style¶

(module)

A module for setting the current drawing style used with various graphics functions in Codea, such as line()

General¶

style.push()¶

Push the current style onto the stack

Returns:: The style table, for chaining.
Return type:: style

style.push(style)

Push a specific style onto the stack

Returns:: The style table, for chaining.
Return type:: style

style.pop()¶

Pop the current style from the stack, restoring the previous style

Returns:: The style table, for chaining.
Return type:: style

style.reset()¶

Reset the current style to defaults. Use this to restore the default style

Returns:: The style table, for chaining.
Return type:: style

style.get()¶: Gets the current style as a graphicsStyle object, allowing styles to be saved and restored arbitrarily

style.set(style)¶

Sets the current style from a graphicsStyle object

Returns:: The style table, for chaining.
Return type:: style

style.fill(color)¶

Sets the fill color for use in vector drawing operations

Returns:: The style table, for chaining.
Return type:: style

style.fill() → r, g, b, a: Gets the current fill color for use in vector drawing operations

style.noFill()¶

Disables fill

Returns:: The style table, for chaining.
Return type:: style

style.stroke(color)¶

Sets the stroke color to the specified color, or a grayscale value

Returns:: The style table, for chaining.
Return type:: style

Parameters:: color (color or number) – The color to set the stroke to, or a grayscale value

style.stroke(gray, alpha)

Sets the stroke color to the specified grayscale value and alpha

Returns:

The style table, for chaining.

Return type:

style

Parameters:

gray (number) – The grayscale value to set the stroke to
alpha (number) – The alpha value to set the stroke to

style.stroke(red, green, blue)

Sets the stroke color to the specified red, green, and blue values

Returns:

The style table, for chaining.

Return type:

style

Parameters:

red (number) – The red value to set the stroke to
green (number) – The green value to set the stroke to
blue (number) – The blue value to set the stroke to

style.stroke(red, green, blue, alpha)

Sets the stroke color to the specified red, green, blue, and alpha values

Returns:

The style table, for chaining.

Return type:

style

Parameters:

red (number) – The red value to set the stroke to
green (number) – The green value to set the stroke to
blue (number) – The blue value to set the stroke to
alpha (number) – The alpha value to set the stroke to

style.stroke(): Gets the current stroke color for use in vector drawing operations

style.noStroke()¶

Disables stroke

Returns:: The style table, for chaining.
Return type:: style

style.tint(<color>)¶

Sets the tint color for use with sprite() and mesh.draw()

Returns:: The style table, for chaining.
Return type:: style

style.tint() → r, g, b, a: Gets the current tint color

style.pixelScaling(scale)¶

Sets/gets the scale of a sprite when rendering

Returns:: The style table, for chaining.
Return type:: style
Parameters:: scale (number) – the scaling factor of the sprite image

style.strokeWidth(width)¶

Sets the stroke width for use in vector drawing operations

Returns:: The style table, for chaining.
Return type:: style

style.strokeWidth() → number: Gets the current stroke width

style.lineCap(mode)¶

Sets the current line cap mode, used by line, polyline and shape

Returns:: The style table, for chaining.
Return type:: style

ROUND
SQUARE
PROJECT

style.lineCap() → enum: Gets the current line cap mode

style.lineJoin(mode)¶

Sets the current line join mode, used by polyline, polygon and shape when joining multiple line segments

Returns:: The style table, for chaining.
Return type:: style

ROUND
MITER
BEVEL

style.lineJoin() → enum: Gets the current line join mode

style.shapeMode(mode)¶

Sets the current shape mode, used by rect, ellipse and sprite

Returns:: The style table, for chaining.
Return type:: style

CENTER - Draw shapes from the center and size using width/height
CORNERS - Draw shapes by specifying the two opposite corners
CORNER - Draw shapes by specifying the bottom left corner and then width/height
RADIUS - Draw shapes by specifying center and radius

style.shapeMode() → enum: Gets the current shape mode

Constants - Shape Mode¶

CORNER: const¶

CORNERS: const¶

CENTER: const¶

RADIUS: const¶

style.sortOrder(order)¶

Returns:: The style table, for chaining.
Return type:: style

Blending Style¶

Functions¶

style.blend(mode)¶

Sets the current blend mode to one of the available presets. Blending composites pixels onto the current drawing context based on source and destination color and alpha values

Returns:: The style table, for chaining.
Return type:: style

The default mode is NORMAL which applies standard alpha blended transparency with the following equation:

\[RGBA = RGBA_{s} * A_{s} + RGBA_{d} * (1-A_{s})\]

DISABLED can be used to disable alpha blending entirely

style.blend(src, dst)

Sets a custom blend mode for both rgb and alpha components using src (source) and dst destination blending factors

Returns:: The style table, for chaining.
Return type:: style

style.blend(src, dst, srcAlpha, dstAlpha)

Sets a custom blend mode with separate blending factors for both rgb and alpha components

Returns:: The style table, for chaining.
Return type:: style

style.blend() → src, dst, srcAlpha, dstAlpha: Returns the current blend factors for both rgb and alpha components (regardless of how the blend modes were set)

style.blendFunc(func)¶

Sets the same blend function for both rgb and alpha components (the default is EQUATION_ADD) which determines how source and destination parts of the blending equation are combined

Returns:: The style table, for chaining.
Return type:: style

EQUATION_ADD - Add (default)
\(R = R_s*k_s+R_d*k_d\)
EQUATION_SUB - Subtract
\(R = R_s*k_s-R_d*k_d\)
EQUATION_REVSUB - Reverse subtract
\(R = R_d*k_d-R_s*k_s\)
EQUATION_MIN - Minimum (blend factors are ignored)
\(R = min(R_s, R_d)\)
EQUATION_MAX - Maximum (blend factors are ignored)
\(R = max(R_s, R_d)\)

style.blendFunc(func, alphaFunc)

Sets separate blend functions for rgb and alpha components

Returns:: The style table, for chaining.
Return type:: style

style.blendFunc() → func, alphaFunc: Returns the current blend function for both rgb and alpha components (regardless of how the functions were set)

Constants - Blend Modes¶

NORMAL: const¶: The default blend mode (alpha blended transparency)

ADDITIVE: const¶: Additive blend mode

MULTIPLY: const¶: Multiply blend mode

SCREEN: const¶: Screen blend mode

LIGHTEN: const¶: Lighten blend mode

LINEAR_BURN: const¶: Linear burn blend mode

PREMULTIPLIED: const¶: Premultiplied blend mode

DISABLED: const¶: Disables blending

Constants - Blend Functions¶

EQUATION_ADD: const¶: Combines source and destination pixels using addition

EQUATION_SUB: const¶: Combines source and destination pixels using subtraction

EQUATION_REVSUB: const¶: Combines source and destination pixels using subtraction in reverse order

EQUATION_MIN: const¶: Combines source and destination pixels by taking the minimum of each component (ignores blend factors)

EQUATION_MAX: const¶: Combines source and destination pixels by taking the maximum of each component (ignores blend factors)

Constants - Blend Factors¶

ZERO: const¶: Blend factor of \((0, 0, 0, 0)\)

ONE: const¶: Blend factor or \((1, 1, 1, 1)\)

SRC_COLOR: const¶: Blend factor of \((R_s, G_s, B_s, A_s)\)

ONE_MINUS_SRC_COLOR: const¶: Blend factor of \((1-R_s, 1-G_s, 1-B_s, 1-A_s)\)

SRC_ALPHA: const¶: Blend factor of \((A_s, A_s, A_s, A_s)\)

ONE_MINUS_SRC_ALPHA: const¶: Blend factor of \((1-A_s, 1-A_s, 1-A_s, 1-A_s)\)

DST_ALPHA: const¶: Blend factor of \((A_d, A_d, A_d, A_d)\)

ONE_MINUS_DST_ALPHA: const¶: Blend factor of \((1-A_d, 1-A_d, 1-A_d, 1-A_d)\)

DST_COLOR: const¶: Blend factor of \((R_d, G_d, B_d, A_d)\)

SRC_ALPHA_SATURATE: const¶: Blend factor of \((f, f, f, 1)\) where \(f = min(A_s, 1 - A_d)\)

Viewport¶

style.viewRect(x, y, w, h)¶

Sets the viewport of the renderer

Returns:

The style table, for chaining.

Return type:

style

Parameters:

x (number) – The x position of the viewport
y (number) – The y position of the viewport
w (number) – The width of the viewport
h (number) – The height of the viewport

Clipping¶

style.clip(x, y, w, h)¶

Settings the clipping rectangle, limiting drawing to within the clipping region

Note: the clipping rectangle is effected by the current matrix transform

Returns:: The style table, for chaining.
Return type:: style

style.noClip()¶

Disables clipping

Returns:: The style table, for chaining.
Return type:: style

Stencil¶

style.stencil(state)¶

Sets the current stencil state for both front and back faces

Returns:: The style table, for chaining.
Return type:: style

style.stencil(): Gets the current stencil state for both front and back faces

style.stencil(front, back)

Sets the current stencil state for front and back faces separately

Returns:: The style table, for chaining.
Return type:: style

Using Stencils¶

A stencil state is configured using a table with the following properties:

reference
condition
readMask
pass
fail
zfail

A simple mask effect using stencils¶

function draw()
   background(40, 40, 50)

   -- When a pixel is drawn write 1 to the stencil buffer
   style.stencil
   {
      reference = 1,
      pass = STENCIL_OP_REPLACE
   }

   -- Use opacity clip to only draw pixels when alpha is greater than .99
   style.opacityClip(0.99)
   style.blend(DISABLED) -- no blending needed
   matrix.push().transform2d(CurrentTouch.x, CurrentTouch.y, 1, 1, time.elapsed * 50)
   sprite(asset.builtin.Cargo_Bot.Codea_Icon, 0, 0, 400)
   matrix.pop()

   style.blend(NORMAL)
   style.noOpacityClip()
   -- Only draw if stencil is equal to one using the equal test condition
   style.stencil
   {
      reference = 1,
      condition = STENCIL_TEST_EQUAL
   }
   sprite(asset.builtin.SpaceCute.Beetle_Ship, WIDTH/2, HEIGHT/2, 400)
end

Stencil Test¶

STENCIL_TEST_LESS: const¶

STENCIL_TEST_LEQUAL: const¶

STENCIL_TEST_EQUAL: const¶

STENCIL_TEST_GEQUAL: const¶

STENCIL_TEST_GREATER: const¶

STENCIL_TEST_NOTEQUAL: const¶

STENCIL_TEST_NEVER: const¶

STENCIL_TEST_ALWAYS: const¶

Stencil Operations¶

STENCIL_OP_ZERO: const¶

STENCIL_OP_KEEP: const¶

STENCIL_OP_REPLACE: const¶

STENCIL_OP_INCREMENT_WRAP: const¶

STENCIL_OP_INCREMENT: const¶

STENCIL_OP_DECREMENT_WRAP: const¶

STENCIL_OP_DECREMENT: const¶

STENCIL_OP_INVERT: const¶

Text Style¶

style.fontSize(size)¶

Returns:: The style table, for chaining.
Return type:: style

style.textAlign(align)¶

Returns:: The style table, for chaining.
Return type:: style

style.textStyle(style)¶

Returns:: The style table, for chaining.
Return type:: style

Constants - Text¶

LEFT: const¶

CENTER: const

RIGHT: const¶

TOP: const¶

MIDDLE: const¶

BOTTOM: const¶

BASELINE: const¶

Constants - Style¶

ROUND: const¶

SQUARE: const¶

PROJECT: const¶

MITER: const¶

BEVEL: const¶

Constants - Render Queues¶

BACKGROUND: const¶

OPAQUE: const¶

TRANSPARENT: const¶

OVERLAY: const¶

Constants - Color Mask¶

Used by shaders to control which color components are written to color buffers (i.e. images and the main context)

COLOR_MASK_NONE: const¶

COLOR_MASK_RED: const¶

COLOR_MASK_GREEN: const¶

COLOR_MASK_BLUE: const¶

COLOR_MASK_ALPHA: const¶

COLOR_MASK_RGB: const¶

COLOR_MASK_RGBA: const¶

Constants - Culling¶

Used by shaders / meshes to control which triangles are culled (based on winding order)

CULL_FACE_NONE: const¶

CULL_FACE_FRONT: const¶

CULL_FACE_BACK: const¶

Constants - Depth¶

Used by shaders to control depth rejection for opaque and translucent fragments

DEPTH_WRITE_ENABLED: const¶

DEPTH_WRITE_DISABLED: const¶

DEPTH_FUNC_NEVER: const¶

DEPTH_FUNC_LESS: const¶

DEPTH_FUNC_EQUAL: const¶

DEPTH_FUNC_LESS_EQUAL: const¶

DEPTH_FUNC_GREATER: const¶

DEPTH_FUNC_NOT_EQUAL: const¶

DEPTH_FUNC_GREATER_EQUAL: const¶