graphics commands
=================

*(global)*

Background
##########

.. lua:function:: background(red, green, blue, alpha)

   Clears the current context with solid color, can also be used to set image backgrounds when combined with :lua:func:`context.push`

   :param red: The red component of the color (0-255)
   :type red: number
   :param green: The green component of the color (0-255)
   :type green: number
   :param blue: The blue component of the color (0-255)
   :type blue: number
   :param alpha: The alpha component of the color (0-255)
   :type alpha: number

   .. helptext:: set the background color
   .. editor:: color

.. lua:function:: background(color)

   Clears the current context with solid color, can also be used to set image backgrounds when combined with :lua:func:`context.push`

   :param color: The color to set the background to
   :type color: color

   .. helptext:: set the background color
   .. editor:: color      

.. lua:function:: background(cubeImage, [mipLevel = 0])

   Clears the current background with the contents of a cube image, using the current camera settings to define eye direction

   .. helptext:: clear the background with a cube image

   :param cubeImage: The image to clear the background with
   :type cubeImage: image
   :param mipLevel: The mip level of the image to use, useful for displaying pre-blurred image mips, such as those calculated using :lua:meth:`image.generateIrradiance`
   :type mipLevel: number

.. lua:function:: background(shader)

   Clears the current background using a custom shader

   :param shader: The shader to use when clearing the background, should be a shader that is compatible with sprite rendering (i.e. uses the same vertex attributes)
   :type shader: shader

   .. helptext:: clear the background with a shader

   .. collapse:: Example

      .. literalinclude:: /code/Background Shader.codea/Main.lua
         :language: lua

Vector Graphics
###############

A set of graphics functions which are so commonly used they are in the global namespace for convenience

.. lua:function:: line(x1, y1, x2, y2)

   Draws 2D line from the start point (x1, y1) to the end point (x2, y2) based on the current style:

   :param x1: the x coordinate of the start point
   :type x1: number
   :param y1: the y coordinate of the start point
   :type y1: number
   :param x2: the x coordinate of the end point
   :type x2: number
   :param y2: the y coordinate of the end point
   :type y2: number

   - *Color* with :lua:func:`style.stroke`
   - *Width* with :lua:func:`style.strokeWidth`
   - *End Caps* with :lua:func:`style.lineCapMode`
      - |square_cap| :lua:attr:`SQUARE`
      - |project_cap| :lua:attr:`PROJECT`
      - |round_cap| :lua:attr:`ROUND`

   .. |square_cap| image:: /images/example_lineCap_SQUARE.png
      :width: 100

   .. |round_cap| image:: /images/example_lineCap_ROUND.png
      :width: 100

   .. |project_cap| image:: /images/example_lineCap_PROJECT.png
      :width: 100

   .. helptext:: draw a line between two points

.. lua:function:: line(x, y)

   Variation of line command used as part of shape drawing

   .. helptext:: draw a line between two points

.. lua:function:: polyline(x1, y1, x2, y2, ... xn, yn)

   Draws a continuous 2D line with an arbitrary number of points (x1, y1, etc...) based on the current style

   - *Color* with :lua:func:`style.stroke`
   - *Width* with :lua:func:`style.strokeWidth`
   - *End Caps* with :lua:func:`style.lineCap`
   - *Line Joins* with :lua:func:`style.lineJoin`
      - |round_join| :lua:attr:`ROUND`
      - |miter_join| :lua:attr:`MITER`
      - |bevel_join| :lua:attr:`BEVEL`

   .. |round_join| image:: /images/example_lineJoin_ROUND.png
      :width: 100

   .. |miter_join| image:: /images/example_lineJoin_MITER.png
      :width: 100

   .. |bevel_join| image:: /images/example_lineJoin_BEVEL.png
      :width: 100

   .. helptext:: draw a continuous polyline

.. lua:function:: polygon(x1, y1, x2, y2, ... xn, yn)

   Draws a closed 2D polygon with an arbitrary number of points based on the current style

   .. helptext:: draw a closed polygon

.. lua:function:: bezier(x1, y1, cx1, cy1, cx2, cy2, x2, y2)

   Draw a quadratic bezier curve using four points based on the current style

   .. helptext:: draw a cubic bezier curve

.. lua:function:: bezier(cx1, cy1, cx2, cy2, x2, y2)

   Variation of bezier command used as part of shape drawing

   .. helptext:: draw a bezier curve segment

.. lua:function:: arc(x, y, radius, startAngle, endAngle, dir)

   Draws a 2D arc with a given origin, radius and start, end angles + direction

   :param x: x coordinate of the arc origin
   :type x: number
   :param y: y coordinate of the arc origin
   :type y: number
   :param radius: the radius arc
   :type radius: number
   :param startAngle: the start angle of the arc (in degrees)
   :type startAngle: number
   :param endAngle: the end angle of the arc (in degrees)
   :type endAngle: number
   :param dir: the direction of the arc, 1 or clockwise, -1 for anti-clockwise
   :type dir: integer

   .. helptext:: draw a 2D arc

.. lua:function:: ellipse(x, y, w, h)
                  ellipse(x, y, r)

   Draw an ellipse with a given origin point and width / height (or radius)

   .. helptext:: draw a circle or oval

.. lua:function:: rect(x, y, w, h, [radius = 0])

   Draws a rectangle with a given origin point and width / height, origin and sizing behaviour depends on :lua:func:`style.shapeMode`

   Optional parameter ``radius`` specified the corner radius

   :param x: the x coordinate of the rectangle
   :type x: number
   :param y: the y coordinate of the rectangle
   :type y: number
   :param w: the width of the rectangle
   :type w: number
   :param h: the height of the rectangle
   :type h: number
   :param radius: the radius of the rounded corners
   :type radius: number

   .. helptext:: draw a rectangle

.. lua:function:: rect(x, y, w, h, r1, r2, r3, r4)

   Draws a rectangle with a given origin point and width / height, origin and sizing behaviour depends on :lua:func:`style.shapeMode`

   The corner radius of each corner can be set independently using the additional parameters r1, r2, r3 and r4

   :param x: the x coordinate of the rectangle
   :type x: number
   :param y: the y coordinate of the rectangle
   :type y: number
   :param w: the width of the rectangle
   :type w: number
   :param h: the height of the rectangle
   :type h: number
   :param r1: the radius of the top-left corner
   :type r1: number
   :param r2: the radius of the top-right corner
   :type r2: number
   :param r3: the radius of the bottom-right corner
   :type r3: number
   :param r4: the radius of the bottom-left corner
   :type r4: number

   .. helptext:: draw a rectangle with rounded corners      


Sprites
#######

.. lua:function:: sprite(image, x, y, [w, h])
                  sprite(asset.key, x, y, [w, h])
                  sprite(sprite.slice, x, y, [w, h])

   Draws a sprite using an asset - :lua:class:`image`, :lua:class:`asset.key` or :lua:class:`sprite.slice`

   .. helptext:: draw a sprite or image
   .. editor:: sprite


.. lua:function:: sprite(shader, x, y, w, h)

   .. helptext:: draw using a shader
   .. editor:: shader


Text
####

.. lua:function:: text(str, x, y, [w, h])

   Draws one or more lines of text based on the current style. Use the optional width and height parameters to draw a fixed size text box with line wrapping enabled

   .. helptext:: draw text at a location
   .. editor:: text

   - *Text Color* with :lua:func:`style.fill`
   - *Text Outline* with :lua:func:`style.stroke`
   - *Text Outline Thickness* with :lua:func:`style.strokeWidth`
   - *Text Alignment* with :lua:func:`style.textAlign`
      - ``LEFT``
      - ``CENTER``
      - ``RIGHT``
      - ``TOP``
      - ``MIDDLE``
      - ``BOTTOM``
   - *Text Style* with :lua:func:`style.textStyle`
      - ``TEXT_NORMAL``

        - Renders the text normally

      - ``TEXT_BACKGROUND``

        - Renders a rectangle behind the text using the background color

      - ``TEXT_UNDERLINE``

        - Renders a line below the text
        
      - ``TEXT_OVERLINE``

        - Renders a line above the text

      - ``TEXT_STRIKE_THROUGH``

        - Renders a line through the text

      - ``TEXT_BOLD``

        - Renders the text in bold

      - ``TEXT_ITALICS``

        - Renders the text in italics

      - ``TEXT_RICH``

        - Enables rich text, which parses xml tags within the supplied string to format individual characters.

      - ``TEXT_UPPERCASE``

        - Renders all text in uppercase

      - ``TEXT_LOWERCASE``

        - Renders all text in lowercase

      - ``TEXT_NATIVE``

        - Enables native text rendering, which uses the system font renderer to draw text and supports emojis. Note that other text styles are disabled while using the native renderer.

   **Built-In Tags**

   *Bold and Italic*

   .. epigraph::

      The <i>quick brown fox</i> jumps over the <b>lazy dog</b>.

      .. image:: /images/example_richText_bold_italic.png
         :width: 512

   *Custom Tags*

   Custom tags can assigned using a callback function - ``text.style.myCustomTag = function(tag, format) ... end``

   The ``tag`` parameter gives access to custom xml tag attributes

   The ``format`` parameter gives access to text formatting options that can be adjusted per tag, derived from text styles in the ``style`` module

   - ``textAlign``
   - ``textStyle``
   - ``fontSize``
   - ``fontName``
   - ``fillColor``
   - ``strokeColor``
   - ``strokeWidth``
   - ``textOverline``
   - ``textUnderline``
   - ``textStrikeThrough``
   - ``textBackground``
   - ``textShadow``
   - ``textShadowOffset``
   - ``textShadowSoftner``
   - ``callback``

   The additional parameter ``callback`` is a special function used to modify individual glyphs (characters) when the text is rendered. The callback function has the following parameters:

   - ``str`` - the string being drawn
   - ``index`` - the index of the current glyph in the string
   - ``mod`` - a reference to a glyphModifier object, used to modify the current glyph

   A ``glyphModifier`` has the follwing properties:

   - ``offsetX`` - the amount to offset the glyphs x position in pixels
   - ``offsetY`` - the amount to offset the glyphs y position in pixels
   - ``alpha`` - the alpha of the current glyph (0-255)
   - ``color`` - the color the of the current glyph

   .. collapse:: Example

      .. literalinclude:: /code/Example_text_glyph_callback.codea/Main.lua
         :language: lua

   :param x: the x coordinate of the text
   :param y: the x coordinate of the text
   :param w: optional width of the text box
   :param h: optional height of the text box
   :param callback: a special glyph modifier callback

.. lua:function:: textSize(str[, width])

   Gets the size of a text being drawn

   .. helptext:: get the width and height of the drawn string

   :param str: the text to query
   :type str: string
   :param width: the width of the textbox
   :type width: number
   :return: The ``width`` and ``height`` of the text 
   :rtype: number, number

Gizmos
######

Gizmos are useful for drawing shapes in 2D/3D space for debugging and editing

.. lua:module:: gizmos

.. lua:function:: line(x1, y1, z1, x2, y2, z2)

   Draws a 3D antialiased line

   .. helptext:: draw a line between two points

Color Space
###########

.. lua:currentmodule:: None

.. lua:function:: colorspace(type)

   Changes the color space used for drawing images and sprites

   :param type: Either ``GAMMA`` or ``LINEAR``

   .. helptext:: set the drawing color space

Contexts
########

.. lua:module:: context

.. lua:function:: push(image, [layer = 0, mip = 0])

   Pushes an :lua:class:`image` to the context, causing subsequent drawing operations to be applied to said image until :lua:func:`context.pop` is called

   :param image: The image to push
   :param layer: The layer of image to draw to
   :param mip: The mip of the image to draw to

   .. helptext:: push an image onto the drawing context

.. lua:function:: pop

   Pops the current image from the context if one exists, subsequent drawing operations are again applied to the main context (i.e. the display)

   .. helptext:: pop the current image from the drawing context