<h2>Name</h2>

<b>dmtx::*</b> - interface to the Data Matrix Code scanner library.

<h2>Synopsis</h2>

<tt>package require dmtx</tt><br>
<tt>dmtx::decode ?options?</tt><br>
<tt>dmtx::async_decode ?options?</tt>

<h2>Description</h2>

These commands are used to scan Data Matrix Codes off pixel image data.

<tt>dmtx::decode <i>photoEtc</i> ?<i>scale

    Scans the photo image for Data Matrix Code information. Alternatively, can be a four element list describing a greyscale or RGB image as a byte array. The elements must be width, height, depth and byte array of the image in this order. The optional integer parameter downsamples the image before the scan takes place. The optional limits the scan process to that many milliseconds. The command returns a three element list made up of a flag indicating success (=1) or failure (=0) of the scan process, the amount of milliseconds spent on decoding, and the scan result as a byte array.

<tt>dmtx::async_decode <i>photoEtc callback</i> ?<i>scale

    Similar to <tt>dmtx::decode</tt> but the decoder is run as a background thread and the result is presented to a procedure. It requires the Tcl core being built with thread support, and a running event loop since the callback is invoked as an event or do-when-idle handler. Three additional arguments are passed to a flag indicating success (=1) or failure (=0) of the scan process, the number of milliseconds for decoding, and the scan result as a byte array. The optional parameters and have the same meaning as in the <tt>dmtx::decode</tt> command. The default timeout value is 1000 milliseconds. Caution: only a single thread instance is supported per Tcl interpreter, i.e. another asynchronous decode process can only be started when a previous decode process has finished.

<tt>dmtx::async_decode abort</tt>

    Aborts a running asynchronous decode process.

<tt>dmtx::async_decode status</tt>

    Returns the current state of the asynchronous decode as a string: when no asynchronous decode thread has been started, when a asynchronous decode is in progress, and when the next asynchronous decode can be started.

<tt>dmtx::async_decode stop</tt>

    Stops the background thread for asynchronous decoding if it has been implicitely started by a prior <tt>dmtx::async_decode</tt>. This can be useful to conserve memory resources.