Download CInk

Download version 2

License terms and conditions - GPLv3.

Important Notes:-

• Version 1 was never released for download.
• You should read the section "CInk caveats" on Learning CFDG2 to understand how z-indices are handled. This is important.

Dependencies

• CInk needs jQuery to handel z-index and Predefined Event Rules.
• When the code has multiple definitions of the same rule then at runtime any one of them is randomly picked. This allows designers to generate random patterns from the same code. These different patterns are called variants. If you want the ability to regenerate a particular variant later then CInk will need the help of seedrandom. At render time if CInk finds this script then it will return a variant name, later which can be passed to it to redraw that variant.

API Reference

All CInk functionalities are available via the globally available object CInk.

CInk.Compile()

• Purpose: Compiles CFDG code.
• Signature: CInk.Compile(rawCode)
• Arguments:
  • rawCode - The CFDG code as string.
• Returns: The compiled code as Javascript object, or null if it couldn't be compiled. Errors and warnings are reported by CInk.err and CInk.warn.

CInk.log()

• Purpose: This is called by CInk to report any informational messages. The default behavior is to log this to Javascript console (in Chrome) and Firebug console in Firefox. This can be overridden to capture these messages. If you override this then maybe you can use the following code to prepare space delimited message from arguments.

  var args = Array.prototype.slice.call(arguments).join(' ');

• Signature: CInk.log()
• Arguments:
  • arguments - This is Javascript provided variable which captures all arguments passed to a method. This API can be passed any number of arguments. Just like console.log.
• Returns: Nothing.

CInk.err()

• Purpose: This is called by CInk to report any errors. This is behaves exactly like CInk.log. This too should be overridden to capture error messages.
• Signature: CInk.err()
• Arguments:
  • arguments - This is Javascript provided variable which captures all arguments passed to a method. This API can be passed any number of arguments. Just like console.error.
• Returns: Nothing.

CInk.warn()

• Purpose: This is called by CInk to report any warnings. This is behaves exactly like CInk.log. This too should be overridden to capture warning messages.
• Signature: CInk.warn()
• Arguments:
  • arguments - This is Javascript provided variable which captures all arguments passed to a method. This API can be passed any number of arguments. Just like console.warn.
• Returns: Nothing.

CInk.Renderer()

• Purpose: This is the one which renders the code on canvas. This is not a method but a 'class' and needs to instantiated with the new operator. Objects of this are intended to be used only once. So when one design has been rendered then for the next design you should get a new instance.
• Signature: CInk.Renderer(canvas, compiledCode, callBackOnFinish)
• Arguments:
  • canvas - The HTML canvas DOM object.
  • compiledCode - The compiled code as returned by CInk.Compile. It is assumed that this code has not been manipulated by you, so if you mess something up in the compiled code then renderer might throw up random errors.
  • callBackOnFinish (Optional) - This is a call-back function which will be called when rendering is complete. If your code has events then too this will be called only once, when the main thread finished rendereing. When a event triggered rendering completes, this won't be called.

    Expected signature of the call-back function - callBackOnFinish(isSuccessful, errMsg). Sometimes runtime errors could be retunred via this method.

• Example Usage: var renderer = new CInk.Renderer(canvas, compiledCode, callBackOnFinish);

  renderer could be null if Renderer couldn't be instantiated.

renderer.render()

• Purpose: This is a public method of Renderer. This starts the rendering process.
• Signature: <Renderer object>.render(variantName)
• Arguments:
  • variantName (Optional) - When passed, this is used to seed the pseudo random number generator. This allows CInk to recreate a known variant. This requires seedrandom.js. See "Dependencies" section above.
• Returns: Nothing or variant name of the current pattern (but only if seedrandom.js is present).

renderer.shutAndDispose()

• Purpose: This is a public method of Renderer. This stops/cancels the rendering process. This can be called anytime, but after its called you should use a new instance of Renderer for the next job. If shut down is already in progress when it is called then it would be ignored and a warning message would be logged.
• Signature: <Renderer object>.shutAndDispose(callOnDisposeFinish)
• Arguments:
  • callOnDisposeFinish (Optional) - This call-back function will be executed when the shut down process is complete. CInk needs time to shut itself down.
• Returns: Nothing.

renderer.MAX_THREADS

• Purpose: This is a public variable of Renderer, and if needed should be after Renderer is instantiated and before calling render(). This controls how many tasks² are run in a single cycle. Default is 30.
• Signature: <Renderer object>.MAX_THREADS

renderer.GLOBAL_SCALE

• Purpose: This too is a public variable of Renderer. This value controls how much the whole design needs to be magnified. Default is 300. So, 1 unit of CFDG is actually equal to 1*300 = 300.
• Signature: <Renderer object>.GLOBAL_SCALE

CInk.compileAndRun()

• Purpose: This is a convinience method. As its name suggests it expects the raw code and it will compile it and render it. This method can be passed the same canvas DOM again and again, and it will take care of cleaning it before use.
• Signature: CInk.compileAndRun(rawCode, canvas, callBackOnFinish, getMeta, variantName, slowClear)
• Arguments:
  • rawCode - The raw code string.
  • canvas - The HTML canvas DOM.
  • callBackOnFinish (Optional) - See CInk.Renderer() for details.
  • getMeta (Optional) - This call-back method's expected signature is getMeta(variantName, compiledCode). They would be set to '' and null in case of error.
  • variantName (Optional) - See renderer.render() for details.
  • slowClear (Optional) - When passed the canvas would be cleared using the clearRect() api of HTML. You need to set this if browser is Chrome, because as of version 12, Chrome has a nasty bug where it fails to render stroked text¹.
• Returns: The instance of Renderer or null in case of error.

CInk.resetCompileAndRun()

• Purpose: This is a convinience method. It does the job of compileAndRun() plus it also takes care of shutting down the Renderer, in case if it is still running. If it finds Renderer running then it invokes its shutAndDispose() and waits till it completely shuts down, before invoking compileAndRun(). If we do not do this then the old and new Renderer objects will simultaneously render on the same canvas!
• Signature: CInk.resetCompileAndRun(params)
• Arguments:
  • params - This should be a Javascript singleton object; defined as params = {};.

    params is used to pass on the arguments needed by compileAndRun(). So to pass on canvas, params.canvas should be defined and so on. resetCompileAndRun() will add rendererVar to it. rendererVar contains the reference to current Renderer instance. You can access this object if you want, but don't set it to null or tamper with it.

• Returns: Nothing.

CInk.resetAndRun()

• Purpose: This is a convinience method. It is similar to resetCompileAndRun(), except that it doesn't compile the code and that needs to be supplied to it. Similar to resetCompileAndRun(), it also takes care of shutting down the Renderer, in case if it is still running. If it finds Renderer running then it invokes its shutAndDispose() and waits till it completely shuts down. If we do not do this then the old and new Renderer objects will simultaneously render on the same canvas!
• Signature: CInk.resetAndRun(params)
• Arguments:
  • params - This should be a Javascript singleton object; defined as params = {};.

    params takes the exact arguments as accepted by resetCompileAndRun(), except for params.rawCode. The compiled code needs to be set to params.compiledCode. This method will later add rendererVar to it; rendererVar contains the reference to current Renderer instance. You can access this object if you want, but don't set it to null or tamper with it.

• Returns: Nothing.

What's more?

Scout through the links on the navigation menu on the left.

1. http://code.google.com/p/chromium/issues/detail?id=44017 (Chrome bug for stroke text)
2. Learning CFDG2 (See CInk caveats: Paths gotcha)