File builtin/vn/image.lua

image.lua Provides the 'built-in' VN image functions.

Functions

bg (tex, props) Changed the current background
bgf (tex, fadeTime, props) Crossfades to a new background
button (filename) Creates a new on-screen button
colorTex (argb, w, h) Creates a new texture with the specified width/height and color.
createCamera (layer) Creates a new camera object
createLayer (layer) Creates a new layer
fadeTo (i, targetAlpha, speed) Gradually changes the alpha of i to targetAlpha.
getBackground () Returns the current background
getImageLayer () Returns the current image layer
getImageStateAttribute (key) Returns the value of an attribute that gets pushed/popped together with the image state.
getOverlayLayer () Returns the overlay layer which is usually the topmost layer.
getRootLayer () Returns the root layer
getSpriteSlotPosition (i, slot, y) Returns the x, y, z of the specified sprite slot (lc, l, c, rc, r)
img (tex, x, y, props) Creates an image
imgf (...) Creates an image and fades it in
popImageState () The inverse of pushImageState, restores the image state to the stored copy.
popLayerState (layer) Pops the top of the layer's state stack, overwriting the current set of active images.
preload (...) Suggests the filenames givens as arguments should be preloaded
pushImageState () Stores a copy of the current image state on a stack then clears the current image state.
pushLayerState (layer, z) Saves the current images onto a stack to be restored later with popLayerState.
rm (i) Removes and image immediately
rmbg (...) Removes the background image previously created with bg
rmbgf (...) Removes the background image after first fading it out
rmf (i, fadeTime) Removes an image after first fading it out
screen2image (layer, z, clip, volatile) Takes a screenshot and makes an image out of it.
screenshot (layer, z, clip, volatile) Takes a screenshot to be used later to create an image drawable
setImageLayer (l) Changes the current image layer
setImageStateAttribute (key, val) Sets an attribute that gets pushed/popped upon calls to pushImageState, popImageState
tex (arg, suppressErrors) Converts the input argument to a texture object if possible
textimg (text) Creates a new textbox
translateRelative (i, dx, dy, frames, interpolator) Gradually offsets the position(s) of i by (dx, dy).
translateTo (i, x, y, frames, interpolator) Gradually changes the position of i to (x, y).
viewCG () Runs the view CG mode


Functions

bg (tex, props)
Changed the current background

Parameters:

  • tex: A texture object or a path to a valid image file
  • props: A table of property overrides to pass to img internally.

Return value:

    The newly created background
bgf (tex, fadeTime, props)
Crossfades to a new background

Parameters:

  • tex: A texture object or a path to a valid image file
  • fadeTime: The fade time (in frames) of the crossfade. Defaults to 30 (0.5 seconds).
  • props: A table of property overrides to pass to bg internally.

Return value:

    The newly created background
button (filename)
Creates a new on-screen button

Parameters:

  • filename: Path to a valid image

Return value:

    The newly created button
colorTex (argb, w, h)
Creates a new texture with the specified width/height and color.

Parameters:

  • argb: The ARGB color packed into a single int (0xFFFF0000 is red, 0xFF0000FF is blue, etc.)
  • w: The height for the generated texture
  • h:

Return value:

    A new texture (w,h) with all pixels colored argb
createCamera (layer)
Creates a new camera object

Parameters:

  • layer: The layer to create the camera on.

Return value:

    The newly created camera object.
createLayer (layer)
Creates a new layer

Parameters:

  • layer: The parent layer for the newly created layer.

Return value:

    The newly created layer, or null if a layer with the given id already exists.
fadeTo (i, targetAlpha, speed)
Gradually changes the alpha of i to targetAlpha.

Parameters:

  • i: The image to change the alpha of.
  • targetAlpha: The end alpha for i
  • speed: The change in alpha each frame (will be multiplied with effectSpeed internally), should always be positive.
getBackground ()
Returns the current background

Return value:

    The current background image, or nil if there's no background currently set.
getImageLayer ()
Returns the current image layer
getImageStateAttribute (key)
Returns the value of an attribute that gets pushed/popped together with the image state.

Parameters:

  • key: The name of the attribute to get the value of

Return value:

    The current value of the attribute specified by key

See also:

getOverlayLayer ()
Returns the overlay layer which is usually the topmost layer.
getRootLayer ()
Returns the root layer
getSpriteSlotPosition (i, slot, y)
Returns the x, y, z of the specified sprite slot (lc, l, c, rc, r)

Parameters:

  • i: The image to position
  • slot: The sprite slot (a string)
  • y: The baseline y (sprite bottom y-coordinate)

Return value:

    Three values, the natural x, y, z for the image in the specified sprite slot.
img (tex, x, y, props)
Creates an image

Parameters:

  • tex: A texture object or a path to a valid image file
  • x: Can be either a string or a number. If it's a number, it specifies the leftmost x-coordinate of the image. If it's a string, it can be one of:
    • l
    • lc
    • c
    • rc
    • r
    These refer to predefined sprite positions from left to right.
  • y: If x is given as a string, the desired y-coordinate of the bottom of the sprite. If x is a number, the topmost y-coordinate.
  • props: Optional argument containing a table containing initial values for the new image's properties.

Return value:

    The newly created image
imgf (...)
Creates an image and fades it in

Parameters:

  • ...:

See also:

popImageState ()
The inverse of pushImageState, restores the image state to the stored copy.

See also:

popLayerState (layer)
Pops the top of the layer's state stack, overwriting the current set of active images.

Parameters:

  • layer:
preload (...)
Suggests the filenames givens as arguments should be preloaded

Parameters:

  • ...:
pushImageState ()
Stores a copy of the current image state on a stack then clears the current image state.
pushLayerState (layer, z)
Saves the current images onto a stack to be restored later with popLayerState. Completely clears the layer of all images.

Parameters:

  • layer: The layer to push the state of.
  • z: Optional parameter, if specified only pushes images with image.z >= z.
rm (i)
Removes and image immediately

Parameters:

  • i: The image to remove
rmbg (...)
Removes the background image previously created with bg

Parameters:

  • ...:
rmbgf (...)
Removes the background image after first fading it out

Parameters:

  • ...:
rmf (i, fadeTime)
Removes an image after first fading it out

Parameters:

  • i: The image to remove
  • fadeTime: The duration of the fade-out effect (in frames).
screen2image (layer, z, clip, volatile)
Takes a screenshot and makes an image out of it. Very useful for creating complex fade effects by making it possible to fade out the entire screen as a single image.

Parameters:

  • layer: The layer in which to take the screenshot
  • z: The z-index to take the screenshot at.
  • clip: Whether or not to honor the layer's clipping bounds.
  • volatile: Allow optimizations which may cause the screenshot's pixels to disappear at any time.

Return value:

    The newly created image
screenshot (layer, z, clip, volatile)
Takes a screenshot to be used later to create an image drawable

Parameters:

  • layer: The layer in which to take the screenshot. Any layers underneath it will be visible in the screenshot. Passing nil for the layer param takes a screenshot of everything.
  • z: The z-index in the selected layer to take the screenshot at.
  • clip: Whether or not to honor the layer's clipping bounds.
  • volatile: Allow optimizations which may cause the screenshot's pixels to disappear at any time.

Return value:

    A screenshot object to be used as an argument to the img function later.
setImageLayer (l)
Changes the current image layer

Parameters:

  • l:
setImageStateAttribute (key, val)
Sets an attribute that gets pushed/popped upon calls to pushImageState, popImageState

Parameters:

  • key: The name for the attribute to set
  • val: The new value for the attribute

See also:

tex (arg, suppressErrors)
Converts the input argument to a texture object if possible

Parameters:

  • arg: The value to convert to a texture object
  • suppressErrors: If true suppress any errors
textimg (text)
Creates a new textbox

Parameters:

  • text: The initial text to display (optional)

Return value:

    The newly created textbox
translateRelative (i, dx, dy, frames, interpolator)
Gradually offsets the position(s) of i by (dx, dy).

Parameters:

  • i: A drawable or table of drawables to move
  • dx: The amount to move in the x-direction
  • dy: The amount to move in the y-direction
  • frames: The number of frames the transition should last (gets multiplied with effectSpeed internally)
  • interpolator: A function or interpolator object mapping an input in the range (0, 1) to an output in the range (0, 1).
translateTo (i, x, y, frames, interpolator)
Gradually changes the position of i to (x, y).

Parameters:

  • i: The image to change the position of.
  • x: The end x-pos for i
  • y: The end y-pos for i
  • frames: The number of frames the transition should last (gets multiplied with effectSpeed internally)
  • interpolator: A function or interpolator object mapping an input in the range (0, 1) to an output in the range (0, 1).
viewCG ()
Runs the view CG mode

Valid XHTML 1.0!