--
-- The Lua script environment includes a single Frame object type that is
-- initialized before execution.  The Frame is the main object with which a
-- script interacts with the qosmic application, and it is bound globally to
-- the 'frame' variable.
--
-- The script environment also contains values for the xform variation types.
-- They are globally bound to variables having the same name as the variation,
-- but with only capital letters.  These values are listed at the bottom of
-- this document.
--
-- Be sure to also look at the example.lua and functions.lua scripts in the
-- scripts directory for more examples.
--
-- With each function listed below the optional arguments are given in brackets,
-- and their default values follow an equal sign.
--


--
-- Frame Object Interface
--
frame:get_genome([idx =0])  -- Returns a reference to the Genome type at offset
                            -- idx in the genomes list.  If there is no genome
                            -- at that offset, the list is filled with default
                            -- Genome types up to idx.

frame:num_genomes() -- Returns the number of genomes in the genomes list

frame:render([idx =0, [filename]])  -- Renders the genome at offset idx in the
                                    -- genomes list.  If filename is given, then
                                    -- the rendered image is saved to that file
                                    -- in png format.  If filename is not given,
                                    -- then the preview image is rendered.

frame:update([idx =0, [filename]])  -- Renders the genome at offset idx in the
                                    -- genomes list.  If filename is given, then
                                    -- the rendered image is saved to that file
                                    -- in png format.  If filename is not given,
                                    -- then the GUI is updated and the preview
                                    -- image is rendered.  Use update to redraw
                                    -- the triangles in the figure editor.

frame:load(filename)    -- Load the flam3 xml file given by string filename. The
                        -- existing genome list is cleared beforehand.

frame:save(filename)    -- Saves the current genome list to string in filename
                        -- in flam3 xml format.

frame:copy_genome(a, b) -- Copies the genome at offset a to offset b.  Offset
                        -- 'a' must be a valid genomes offset.

frame:del_genome(idx)   -- Removes the genome at offset idx

frame:bitdepth()        -- Returns the bit depth used to render genomes.




--
-- Genome Type Interface
--
-- The Genome type provides access to the xforms (triangle), palette, and image
-- settings for an entry in the genomes list.  A genome variable value obtained
-- from the frame using frame:get_genome() is not a copy, and it refers directly
-- to the data in the list.

index()             -- Returns the offset for this genome in the genomes list.

center([x,y])       -- The coordinates of the center of the genome.

rot_center([x,y])   -- Rotate around this position

background([r,g,b]) -- Accessor for the background color of the genome.
                    -- Valid values for r,g, and b variables are in [0.0, 1.0].

num_xforms()        -- Returns the number of xforms in the xforms list.

final_xform_index() -- Returns the offset of the final xform.

get_xform(idx)      -- Returns a reference to the XForm at offset idx in the xform
                    -- list for this genome.  The given offset must be a valid
                    -- index.

add_xform([n =1])  -- Add n xform(s) to the xform list.  Returns a reference to
                   -- the last xform added.

del_xform(idx)     -- Removes the xform at offset idx from the xform list.  The
                   -- xforms at higher offsets are re-indexed.

copy_xform(a, b)   -- Copy values in XForm at offset a to the XForm at offset b.
                   -- The first argument may also be a valid XForm type.

clear_xforms()     -- Remove all xform from the list.

load_palette(idx)  -- Load the built-in palette given by idx into the genome's
                   -- palette.

palette(idx, [r,g,b])  -- Get/set the color in the palette at offset idx.  The
                       -- palette is indexed on [0,255], and the color components
                       -- are valid on [0.0,1.0].

width([value])

height([value])

rotate([deg])                   -- rotates the genome

vibrancy([real])

hue_rotation([real])

zoom([value])                   -- deprecated. use image scale + quality instead

pixels_per_unit([value])        -- image scale

spatial_filter_radius([value])  -- filter radius

spatial_filter_select([n])      -- the filter shape to use (see below)

sample_density([value])         -- image quality

brightness([value])

contrast([value])

gamma([value])

time([value])

estimator([value])

estimator_curve([value])

estimator_minimum([value])

gam_lin_thresh([value])

motion_exp([value])

interpolation([value])

interpolation_space([value])

palette_interpolation([value])

final_xform_enable([value])     -- set to 1 if the final xform is used

symmetry([n])                   -- calculate n'th the genome symmetry group

palette_index([value])          -- index of built-in palette is used

spatial_oversample([value])     -- oversample

nbatches([value])               -- passes

ntemporal_samples([value])      -- temporal samples




--
-- XForm Type Interface
--
-- The XForm type returned by a Genome supports the following interface.  An
-- XForm cooresponds to a triangle object in the editor.
--
index()              -- This xform offset in the genome's xform list

density([real])      -- density

symmetry([real])

color(idx, [r, g, b])

var(n, [real])       -- The value of variation 'n'.  'n' may be a string
                     -- containing the variation name, or it may be an integer
                     -- given by one of the global variation variables
                     -- (ie LINEAR, WAVES, ...)

param(n, [real])     -- An alias for var()

o([x,y])             -- The O coordinate for this xform's triangle
a([x,y])             -- An alias for o()

x([x,y])             -- The X coordinate for this xform's triangle
b([x,y])             -- An alias for x()

y([x,y])             -- The Y coordinate for this xform's triangle
c([x,y])             -- An alias for y()

pos([x,y])           -- The coordinates of the center of the xform's triangle.

translate(dx, dy)    -- Move the center of the xform's triangle by dx, dy

rotate(deg,[x,y])    -- Rotate the xform's triangle around pos() if x,y not given

scale(dz,[x,y])      -- Scale the xform's triangle by dz about pos() if x,y not given

shear(dx,dy,[x,y])   -- Shear the xform's triangle by dz about pos() if x,y not given


xa([value])  -- The xform's 'a' value.
xb([value])  -- The xform's 'b' value.
xc([value])  -- The xform's 'c' value.
xd([value])  -- The xform's 'd' value.
xe([value])  -- The xform's 'e' value.
xf([value])  -- The xform's 'f' value.


op([x,y])             -- The O coordinate for this xform's post triangle

xp([x,y])             -- The X coordinate for this xform's post triangle

yp([x,y])             -- The Y coordinate for this xform's post triangle

posp([x,y])           -- The coordinates of the center of the xform's post triangle.

translatep(dx, dy)    -- Move the center of the xform's post triangle by dx, dy

rotatep(deg,[x,y])    -- Rotate the xform's post triangle around pos() if x,y not given

scalep(dz,[x,y])      -- Scale the xform's post triangle by dz about pos() if x,y not given

shearp(dx,dy,[x,y])   -- Shear the xform's post triangle by dz about pos() if x,y not given

xap([value])  -- The xform's post triangle 'a' value.
xbp([value])  -- The xform's post triangle 'b' value.
xcp([value])  -- The xform's post triangle 'c' value.
xdp([value])  -- The xform's post triangle 'd' value.
xep([value])  -- The xform's post triangle 'e' value.
xfp([value])  -- The xform's post triangle 'f' value.



-- The following are accessors for setting the parameters of a given variation
-- in an xform.
precalc_sqrt_flag([value])
precalc_angles_flag([value])
precalc_atan_xy_flag([value])
precalc_atan_yx_flag([value])
blob_low([value])
blob_high([value])
blob_waves([value])
pdj_a([value])
pdj_b([value])
pdj_c([value])
pdj_d([value])
fan2_x([value])
fan2_y([value])
rings2_val([value])
perspective_angle([value])
perspective_dist([value])
juliaN_power([value])
juliaN_dist([value])
juliaScope_power([value])
juliaScope_dist([value])
radialBlur_angle([value])
pie_slices([value])
pie_rotation([value])
pie_thickness([value])
ngon_sides([value])
ngon_power([value])
ngon_circle([value])
ngon_corners([value])
curl_c1([value])
curl_c2([value])
rectangles_x([value])
rectangles_y([value])
amw_amp([value])
disc2_rot([value])
disc2_twist([value])
supershape_rnd([value])
supershape_m([value])
supershape_n1([value])
supershape_n2([value])
supershape_n3([value])
supershape_holes([value])
flower_petals([value])
flower_holes([value])
conic_eccen([value])
conic_holes([value])
parabola_height([value])
parabola_width([value])
split_xsize([value])
split_ysize([value])
split_shift([value])
move_x([value])
move_y([value])
persp_vsin([value])
persp_vfcos([value])
juliaN_rN([value])
juliaN_cn([value])
juliaScope_rN([value])
juliaScope_cn([value])
radialBlur_spinvar([value])
radialBlur_zoomvar([value])
waves_dx2([value])
waves_dy2([value])
disc2_sinadd([value])
disc2_cosadd([value])
disc2_timespi([value])
supershape_pm_4([value])
supershape_pneg1_n1([value])




--
-- Looping and thread control
--
-- The script environment also contains a stopped() function so that scripts
-- can check if they have been requested to stop executing by the controlling
-- application.  This is useful for scripts that may want to use an infinite
-- loop which don't call a qosmic function.

while not stopped() do
	-- ... do something ...
end

-- You can "restart" a stopped script, or reset the stopped() function by
-- passing it a boolean.

if stopped() then
	stopped(false)  -- returns false
end


-- There is also an irand() function that returns a random value between zero
-- and one.  This is the same random number generator that is used by libflam3.

while true do
	print('irand() = ' .. irand())
end


-- Use msleep() to temporarily halt thread execution for one second.

while true do
	print('irand() = ' .. irand())
	msleep(1000)
end



--
-- Variation Types
--
-- The following is a list of the globally bound variables corresponding to the
-- transform variations.  There is also a variable called RANDOM which has a
-- value of -1, and the number of variations available is set in a variable
-- called NUM_VARS.
--
LINEAR
SINUSOIDAL
SPHERICAL
SWIRL
HORSESHOE
POLAR
HANDKERCHIEF
HEART
DISC
SPIRAL
HYPERBOLIC
DIAMOND
EX
JULIA
BENT
WAVES
FISHEYE
POPCORN
EXPONENTIAL
POWER
COSINE
RINGS
FAN
BLOB
PDJ
FAN2
RINGS2
EYEFISH
BUBBLE
CYLINDER
PERSPECTIVE
NOISE
JULIAN
JULIASCOPE
BLUR
GAUSSIAN_BLU
RADIAL_BLUR
PIE
NGON
CURL
RECTANGLES
ARCH
TANGENT
SQUARE
RAYS
BLADE
SECANT
TWINTRIAN
CROSS
DISC2
SUPER_SHAPE
FLOWER
CONIC
PARABOLA


--
-- Filter Shapes
--
-- The following is a list of the globally bound variables corresponding to the
-- spatial kernel shapes that can be used to set/check a genome's
-- spatial_filter_select() accessor.
--
GAUSSIAN_KERNEL
HERMITE_KERNEL
BOX_KERNEL
TRIANGLE_KERNEL
BELL_KERNEL
B_SPLINE_KERNEL
LANCZOS3_KERNEL
LANCZOS2_KERNEL
MITCHELL_KERNEL
BLACKMAN_KERNEL
CATROM_KERNEL
HAMMING_KERNEL
HANNING_KERNEL
QUADRATIC_KERNEL

