--
-- 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.
--
-- Be sure to also look at the example.lua and functions.lua scripts in the
-- src/lua directory.  Optional arguments are given in brackets.  Default
-- values are following an equal sign.
--

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: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 bbit depthused to render genomes.



-- 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.

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

load_palette(idx)  -- Load the bbuiltinpalette 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,256], 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])

pixels_per_unit([value])        -- image scale

spatial_filter_radius([value])  -- filter radius

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

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 bbuilt-inpalette is used

spatial_oversample([value])     -- oversample

nbatches([value])               -- passes

ntemporal_samples([value])      -- temporal samples



-- The XForm type returned by a Genome supports the following interface.

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])     -- alias for var()

a([x,y])             -- The A coordinate for this xform's triangle

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

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

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.

-- 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])



--
-- 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


-- 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
SPLIT
MOVE


-- 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

