/ 
Graphics-GVG-0.92
River stage one • 3 direct dependents • 3 total dependents
++
 / Graphics::GVG

NAME

  Graphics::GVG - Game Vector Graphics

SYNOPSIS

    my $SCRIPT = <<'END';
        %color = #FF33FFFF;

        line( %color, 0.0, 0.0, 1.0, 1.1 );
        glow {
            circle( %color, 0, 0, 0.9 );
            rect( %color, 0, 1, 0.7, 0.4 );
        }
    END

    my $gvg = Graphics::GVG->new;
    my $ast = $gvg->parse( $SCRIPT );

DESCRIPTION

Parses scripts that describe vectors used for gaming graphics. The script is parsed into an Abstract Syntax Tree (AST), which can then be transformed into different forms. For example, Graphics::GVG::OpenGLRender generates Perl code that can be compiled and called inside a larger Perl/OpenGL program.

LANGUAGE

Compared to SVG, GVG scripts are very simple. They look like a series of C function calls, with blocks that generate various effects. Each statement is ended by a semicolon.

The coordinate space follows general OpenGL conventions, where x/y coords are floating point numbers between -1.0 and 1.0, using the right-hand rule.

Comments

Comments start with '//' and go to the end of the line

Operators

There aren't any.

Conditionals

There aren't any.

Loops

There aren't any. I said this was a simple language, remember?

Data Types

GVG functions can take several data types:

  • Integer -- a series of digits with no decimal point, like 1234.

  • Float -- a series of digits, which can contain a decimal point, like 1.234. While you can specify as many digits as you want, note that these are ultimately limited to double-precision IEEE floats.

  • Color -- starts with a '#', and then is followed by 8 hexidecimal digits, in RGBA form, like #5cd2bbff. Hex digits can be upper or lower case.

Integers and floats can both use '-' to indicate a negative number.

The type system is both static and strong; you can't assign an integer to a color parameter.

Variables

Data types can be saved in variables, which each data type getting its own sigal.

    &x = 2; // Integer
    $y = 1.23; // Float
    %color = #ff33aaff; // Color

    poly( %color, 0, $y, 4.3, &x, 30.2 );

Variables can be redefined at any time:

    %color = #ff33aaff;
    line( %color, 0, 1, 1, 0 );
    %color = #aabbaaff;
    line( %color, 1, 0, 1, 1 );

Meta Information

Meta info is general things that renderers may need to work with, and are usually dependent on a larger context. For instance, you might put in a !size = "small";, which might be sized relative to tiny, medium, large, huge, etc. objects in the rest of the system.

Meta statements start with ! and are followed by a name and a value. The value can be a float, integer, or a string (surrounded by double quotes).

    !name = "flying thing";
    !size = "small";
    !side = 1;

Functions

There are several drawing functions for defining vectors.

line

  line( %color, $x1, $y1, $x2, $y2 );

A line of the given %color, going from coordinates $x1,$y1 to $x2,$y2.

circle

  circle( %color, $cx, $cy, $r );

A circle of the given %color, centered at $cx,$cy, with radius $r.

rect

  rect( %color, $x, $y, $width, $height );

A rectangle of the given %color, starting at $x,$y, and then going to $x + $width and $y + $height.

ellipse

  ellipse( %color, $cx, $cy, $rx, $ry );

An ellipse of the given %color, centered at $cx,$cy, with respective radii $rx and $ry.

point

  point( %color, $x, $y, $size );

A point of the given %color, at $x,$y, with size $size.

poly

  poly( %color, $cx, $cy, $r, &sides, $rotate );

A regular polygon of the given %color, centered at $cx,$cy, rotated $rotate degrees, with radius $r, and &sides number of sides.

Effects

Effects can be applied to drawing functions by enclosing them in a block (inside {...} characters) named for a certain effect.

For example, a glow effect can be set on lines with:

    glow {
        circle( %color, 0, 0, 0.9 );
        rect( %color, 0, 1, 0.7, 0.4 );
    }

How this is rendered is dependent on the renderer. An OpenGL renderer may show an actual neon glow effect, while a renderer for a physics library may ignore it entirely.

ABSTRACT SYNTAX TREE

The parse results in an Abstract Syntax Tree, which is represented with Perl objects. Developers writing renderers will need to take the AST and walk it to generate their desired output. See Graphics::GVG::AST for a description of the tree objects.

METHODS

parse

Takes a GVG script as input. On success, returns an abstract syntax tree. Otherwise, throws a fatal error.

LICENSE

    Copyright (c) 2016  Timm Murray
    All rights reserved.

    Redistribution and use in source and binary forms, with or without 
    modification, are permitted provided that the following conditions are met:

        * Redistributions of source code must retain the above copyright notice, 
          this list of conditions and the following disclaimer.
        * Redistributions in binary form must reproduce the above copyright 
          notice, this list of conditions and the following disclaimer in the 
          documentation and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
    POSSIBILITY OF SUCH DAMAGE.