IanniXNotes

See
http://iannix.org
forapplication.
(NoteslastupdatedSeptember14,2011)

IannixDocumentManagement

Scoresarefilesoftype*.ncxscore
Scriptsarefilesoftype*.ncxscript
Onappopen:
allscorefilesinthe"Project"folderareloaded.TheseappearinScoressectioninthe
ScoreCenterintheInspector.
Allscriptsinthe"Project","Tools"and"Examples"foldersareloaded`.Theseappear
inStylesandScriptssectionintheScoreCenterintheInspector.
Whenascoreissavedusingthefilemenu,everythingyouseeinthescoreissaved.
Thiscouldhavebeenconstructedbysomecombinationofmanualeditingandscripts.
Thefilemenuisusedtorename,saveorremovescoresfromthecurrentproject.
Thefilemenuisusedtoopenadifferentprojectfolder
Tocreateanewscriptdoubleclickonthe"NewScript"iteminthe"Scripts&Styles"list
(thisactsasatemplate.)
Itsnotclearhowtocreateanewprojectfolder.AtpresentImnotsurethisispossible
directlyfromIanniX.Ithinkitwouldneedtobedoneinthefilesystem.
Ingeneral,scriptsareusedtoconstructormakebulkchangestoscores
Apparentlyscriptshavenofurthereffectafterascoreisplaying(Ineedtoverifythis)

IanniXScripting
Notes:
Thefollowingnotesonscriptingcommandspartlyduplicatethedocumentationavailable
byclickingonthe?intheIanniXapplication.Thatwouldbeabetterplacetolearn
aboutcommandparameters.Ididntfindtheinappdocumentationforawhile.Asfar
asIknowitsnotavailabledirectlyfromtheIanniXwebsite.)Mydocumentationcovers
abunchofusefulthingsnotmentionedintheofficialdocumentation:asscriptevents,
globalpropertiesandthecommandstopromptforparametersfromtheuser.
TheALLCAPSwordsbelowarethesymbolicnamesofthecommandsintheIanniX
sourcecode(mainlyformyownreference).ProbablyonlyofinteresttoC++developers.
AllcommandsaremethodsoftheIanniXobjectandthusareaccessedwiththesyntax:
run(<commandname>param1param2,,,)
Thecommandandparametersarepassedtoexecuteasasinglestringdelimitedby
spaces,withthefirstfieldofthestringbeingthecommandnameandsubsequentfields
areparameterstothecommand.Inthecaseofcommandsthatactonobjectsthefirst
parameterafterthecommandnameistheidobtheobject.

Iassumethatnonebutthelastparametercancontainspaces,sincespacesare
delimiters.
SeethesetMessageobjectforanexampleofacommandthathasspacesinitslast
parameter.(Ineedtoconfirmthecorrectnessofthisassumption)

CommandtoCreateObjects
run("add<curve|cursor|trigger>id)
COMMAND_ADD
Addsacurve,cursorortriggertothescore
idisanintegeridentificationnumberforthisobject
examples:
run("addcurve1100")
run("addtrigger"+(2000+index))
run("addcursor100")

CommandsThatActonObjects
(firstparameteristheobjecttooperateon)
(allthesecommandstakethetargetobjectasfirstparameter)
(mosttakeadditionalparameters,TBD)
Thefirstparameterofallobjectcommandsis
object:
theintegeridassignedtotheobjectwhenitwascreated.or
current,tocausethecommandtoactontheobjectinthethepreviousobjectcommand.

run("removeobject...")
COMMAND_REMOVE

run("setgroupobjectgroupName")
COMMAND_GROUP

groupName
isthetextnameofagrouptowhichthisobjectshouldbeassigned

run("settriggeroffobject...")
COMMAND_TRIGGER_OFF

run("setcurveobject...")
COMMAND_CURSOR_CURVE

run("setwidthobject...")
COMMAND_CURSOR_WIDTH

run("setpatternobject...")
COMMAND_CURSOR_START

run("setspeedobject)
COMMAND_CURSOR_SPEED

run("setspeedfobject...")
COMMAND_CURSOR_SPEEDF

run("setoffsetobject...")
COMMAND_CURSOR_OFFSET

run("setboundssourceobject...")
COMMAND_CURSOR_BOUNDS_SOURCE

run("setboundstargetobject...")
COMMAND_CURSOR_BOUNDS_TARGET

run("settimeobject...")
COMMAND_CURSOR_TIME

run("
setpointat

object

pointIndex

xCoord

yCoord<zCoord>"
)
COMMAND_CURVE_POINT
Addormodifyapointonacurve
Currentlyonlycurvesmadeofstraightlinesegmentsaresupported)

pointIndex
isthepositionofthepointinthecurve,countingfromthebeginning.
If
pointIndex
isbeyondthenumberofpointsinthecurve,alinesegmentisaddedfromthe
positionofthelastpointonthecurvetoposition(
xCoord

yCoord),
whichbecomesthelast
point.
If
pointIndex
isthepositionofanexistingpoint,thepointpositionischangedto(
xCoord
yCoord).
zCoordisoptional

run("setpointstxtobject...")
COMMAND_CURVE_TXT

run("setpointssvgobject...")
COMMAND_CURVE_SVG

run("setpointssvg2object...")
COMMAND_CURVE_SVG2

run("setpointsimgobject...")
COMMAND_CURVE_IMG

run("setpointsellipseobject)

COMMAND_CURVE_ELL

run("setsizeobject...")
COMMAND_SIZE

run("setresizeobject...")
COMMAND_RESIZE

run("setresizefobject...")
COMMAND_RESIZEF

run("setlineobject...")
COMMAND_LINE

run("setposobjectxPosyPos<zPos>")
COMMAND_POS
Setthepositionofanobject
xPos,yPosarethedesiredposition.zPosisoptional.
example
run("setPoscurrent"+(indexMax/5)+"00")

run("setactiveobject...")
COMMAND_ACTIVE

run("setlabelobjectobject...")
COMMAND_LABEL

run("
setmessageobjectmessage"
)
COMMAND_MESSAGE

SettheOSCmessageofanobject.Formatofmessagedependsonthetypeofmessage.
Example
run("setMessagecurrent100,midi://loopMIDI2/cc00cursor_value_y")

NonObjectCommands

run("clear")
COMMAND_CLEAR

Clearcurrentdocument.

run("sendosc")
COMMAND_MESSAGE_SEND

SendanOSCmessagefromascript?

run("registertexture6arguments")
COMMAND_TEXTURE

run("registercolor5arguments")
COMMAND_GLOBAL_COLOR

run("registercolor25arguments")
COMMAND_GLOBAL_COLOR2

run("settextureactive")
COMMAND_TEXTURE_ACTIVE

run("settextureinactive")
COMMAND_TEXTURE_INACTIVE

run("settextureactivemessage")
COMMAND_TEXTURE_ACTIVE_MESSAGE

run("settextureinactivemessage")
COMMAND_TEXTURE_INACTIVE_MESSAGE

run("setcoloractiveobject...")
COMMAND_COLOR_ACTIVE

run("setcolorinactiveobject...")
COMMAND_COLOR_INACTIVE

run("setcoloractivemessageobject...")
COMMAND_COLOR_ACTIVE_MESSAGE

run("setcolorinactivemessageobject..."
COMMAND_COLOR_INACTIVE_MESSAGE

run("setcoloractive2object...")
COMMAND_COLOR_ACTIVE2

run("setcolorinactiveobject...2")
COMMAND_COLOR_INACTIVE2

run("setcoloractivemessage2object...")
COMMAND_COLOR_ACTIVE_MESSAGE2

run("setcolorinactivemessage2object...")

COMMAND_COLOR_INACTIVE_MESSAGE2

run("autosize")
COMMAND_AUTOSIZE

run("zoompercent")
COMMAND_ZOOM
percentisthepercenttozoom(100=normalsize)

run("centerxcoordiniateycoordinate")
COMMAND_CENTER

xcoordinate,ycoordinatearecoordinatestocentreinthedisplay

run("playplaystatus")
COMMAND_PLAY
Startorstoptransportplaying

playstatus =0startstransport
=nonzerostopstransport

run("stop")
COMMAND_STOP

Stopstransport

run("fastrewind")
COMMAND_FF
Resettransporttostart

run("speed")
COMMAND_SPEED

run("pushsnapshot")
COMMAND_SNAP_PUSH

Savestateforundo

run("popsnapshot")
COMMAND_SNAP_POP
Restorepreviousstate

run("logmessage")
COMMAND_LOG

Sendsmessagetexttolog

CommandstoPromptforDataPriortoRunningaScript
(ThesecommandsarecalledinascriptsonConfigure()procedure.)

iannix.meta("Title")
Setsthetitleofthepromptwindow.

iannix.ask("GroupName","Prompt","VariableName",DefaultValue)
GroupNameisthetextstringthatisthenameofagroupingofdatarequests.Allprompts
withthesameGroupNamelistedunderthatheading.
Promptistextstringusedtopromptforthisdataitem.
VariableNameisthetextstringthatbecomesthenameofthevariablethatwillholdthe
valueofthisitemforuseinthescript.
DefaultValueisthedefaultvaluethatwillbeshownandusediftheuserdoesnotentera
value.

ScriptGlobalProperties
iannix

Theapplicationscommandexecutionobject.Theexecutemethodofthisobjectiscalledto
executecommands(seeabovecommandreference).Examples:
run("clear")
run("setPointAtcurrent1"+x1+""+y1)
Seesamplescriptsformoreexamples.
mouseX

continuallyupdatedwiththecurrentmouseXposition?
mouseX

continuallyupdatedwiththecurrentmouseYposition?
objectId

Isthisthecurrentlyselectedobject?Justaguess.

ScriptEvents
functiononConfigure()

Inthisevent,usercanbepromptedforparametersforthescript.
functiononCreate()

Inthiseventgoesallthecodetobuildthescore
functiononMessage()

CalledineachactivescriptwhenanOSCmessagearrives?
functiononDraw()

Calledineachactivescriptuponeachscorepaintevent.
Currentlydisabledinsourcecode.
functiononLoad()

Calledforeachactivescriptwhenascoreisloaded?
Imnotsurethisisactuallycalledinthecurrentsourcecode.

MessageConstruction
Messages&variablesrelatedtothecursor

Cursormessagesaresentcontinuallyfromeachactivecursorwhilethescoreisplaying.The
message(s)acursorsendscanbeeditedwiththeOSCMessagesbuttonoftheinspector
whenthecursorisselected.

Thedefaultmessageintervalis20milliseconds.Theintervalcanbechangedwiththesent
eachfieldinthemessagefieldoftheinspectorwhenthecursorisselected.

Youcanusethefollowingvariablesinconstructingmessagessentbycursors:

cursor_id
cursorID
cursor_group_id
groupIDofthecursor
cursor_document_id nameoftheproject
cursor_xPos
cursorabscissa
cursor_yPos
cursorordinate
cursor_time
cursorpositiononthecurveinseconds
cursor_time_percent cursorpositiononthecurveinpercent(between0and1)
cursor_value_x
abscissainagreementwiththeBoundsTargetspecified
cursor_value_y
ordinateinagreementwiththeBoundsTargetspecified
cursor_angle
angleofthecursorrelativetothecurve
cursor_nb_loop
numberofcyclesonthecurve

Cursorscanalsosendinformationaboutthecurveonwhichtheyarelocatedandthecurves
theyintersect.

curve_id
IDofthecurveaffectedbythecursor
curve_group_id
groupIDofthecurve
curve_document_id nameoftheproject
curve_xPos
abscissaofthefirstpointofthecurve
curve_yPos
ordinateofthefirstpointofthecurve
Thecollisiondataitemsareonlyavailablewhileacursoriscollidingwithanothercurve.i.e.
Whenanypartofthecursorintersectsanypartoftheothercurve,thesedataitemsare
available.Whenanydataitemusedinamessageisnotavailable,thatareaofthemessageis
leftblank.(Note:Thiscanbeaproblemunlessthedataitemisthelastfieldofamessage.Ifit
isnotthelastfielditsabsencecouldcauseallfieldspastittobemisaligned.)
colliding**
returns1ifcollisionisunderway,0ifnot
collision_curve_id
IDofthecrossedcurve
collision_xPos
xcoordinateoftheintersectionpoint
collision_yPos
ycoordinateoftheintersectionpoint
collison_value_x
xcoordinateoftheintersectionpointmodifiedbyBoundsTarget
collision_value_y
ycoordinateoftheintersectionpointmodifiedbyBoundsTarget

collision_distance** distancefromthecenterofcursortotheintersectionofthecursor
withthecollisioncurve
collision_angle**
angleoflinebetweencenterofcursorandintersectionofthe
cursorwiththecollisioncurve
**AddedinmypersonalversionofIanniX

Messages&variablesrelatedtoatrigger

trigger_id
IDoftheenabledtrigger
trigger_group_id
IDoftheenabledgroup
trigger_document_id nameoftheproject
trigger_xPos
triggerxcoordinate
trigger_yPos
triggerycoordinate
trigger_value
127whenthetriggerisenabledand0whenitisdisable
trigger_distance**
distancefromthecenterofcursortothecenterofthetrigger
trigger_angle**
angleoflinebetweencenterofcursortothecenterofthetrigger
**AddedinmypersonalversionofIanniX

Althoughnotmentionedinthenewdocumentation,triggerscanalsosendthevariablesforthe
thecursorthattriggeredthem.(Seeaboveforcursorvariables).
cursor_id
cursorID
cursor_group_id
groupIDofthecursor
cursor_document_id nameoftheproject
cursor_xPos
cursorxcoordinate
cursor_yPos
cursorycoordinate
cursor_time
cursorpositiononthecurveinseconds
cursor_time_percent cursorpositiononthecurveinpercent(between0and1)
cursor_value_x
xcoordinateinagreementwiththeBoundsTargetspecified
cursor_value_y
ycoordinateinagreementwiththeBoundsTargetspecified
cursor_angle
angleofthecursorrelativetothecurve
cursor_nb_loop
numberofcyclesonthecurve
curve_id
IDofthecurveaffectedbythetriggeringcursor
curve_group_id
groupIDofthecurve
curve_document_id nameoftheproject
curve_xPos
xcoordinateofthefirstpointofthecurve
curve_yPos
ycoordinateofthefirstpointofthecurve
Ideas
Inareceivingapplicationwhenatriggeristriggered,itwouldbepossibletocomputethe
distancetoatrigger,thepanangle(usingthecursor_angle),andtherelativevelocitybetween
thecursorandthetrigger.ButinthecurrentversionofIanniXitwouldnotbepossibletoaccess
thecontinuouslyvaryingangleanddistancebetweenacursorandtrigger.

Byhandlingthenoteoffinthereceivingapplicationitwouldbepossibletooffsetthestartof
notesandmakenotedurationdependonvariousparametersincludingtriggersize.

HowtomakeMIDImessagesresponsivetostatevariablesofthescore?e.g.MIDInotenumber,
controllervalues,etc?StatevariablescanbeusedinMIDImessagesbuttherangeswouldbe
wrong.Couldweprovidesomewayofautorescalinginsyntaxofmessage?(Ihavenow
implementedthisinmypersonalversionofIanniXbyallowingembeddedJavascript
expressionssurroundedby{...}inmessagespecifications).

AtpresentIdontthinkthereisanywaytosendpitchbend.(otherthansendingthedesired
statevariablesusingOSCtoanappsuchasMaxandusingitforintermediateprocessing).(I
havenowimplementedpitchbendinmyversionofIanniXasa/bendmessagetype.

IdontthinkthereisawaytohavethescorecontroltheMIDInoteduration.Iproposethatan
additionaloptionallastparameterbeaddedto/noteMIDImessagesthat,ifprovidedwould
overridethedefaultnoteduration.Itwouldalsobeusefultohavenoteontimetobecontrolled
bythedurationofacollision.i.e.Noteonwouldoccurwhenthecursorfirstcontactsatrigger
andnoteoffwouldbewhencontactends.HoweverIdothinkitwouldbepossibleusingmy
embeddedJavascripttohavecollisionsofcursorswithcurvescontrolnotedurationbyhaving
thepresenceofabsenceofacollisioncontrolnotevelocity,withvelocityzerowhennocollision
isoccurring.

Idea:Havesometriggerscausethenoteonsforparticularnotesandothertriggerssend
velocityzerototurnthemoff?Thereforethespacingbetweenthetriggerswouldcontrolthe
noteduration,whichwouldalsochangedependingonthecurvedirectionofacursorthat
encountersthem.

Issue:
1)IfaTriggerofftimeissetforatrigger,allthemessagesassociatedwiththattriggerareresent
whenthenoteoffoccurseveniftheyarenot/notemessages.e.g.Iwassendinga/bend
precedinga/notemessageinatriggerandthe/bendwasbeingresentonnoteoff,whichwas
affectingothernotes.
2)cursor_anglealwaysseemstobenegative.Thecorrectanglewouldbe(360+cursor_angle)
3)cursor_angledoesnotchangedependingonthedirectionofthecursor,whichitseemsit
shoulddo.Ithinkthatifthecursorismovingrighttolefttheangleshouldbe
(180+cursor_angle)