# -----------------------------------------------------------------------------
#  DF3VT - a SQLite Virtual Table interface to DF3 data files.
# -----------------------------------------------------------------------------

df3vt is part of the df3 tools project.

it provides a loadable extension module for the SQLite3 database which
implements virtual tables exposing given DF3 data files, as defined in
the manual of the Persistence Of Vision Raytracer 3.7.x software.

building requires a 64-bit GNU/Linux os(*), the usual GCC tool chain,
and the 'df3' external library.  read the introductory comments in the
'df3vt.c' source file, then execute:

  $ make

since the extension is for personal use, no installation target is
provided; simply copy the 'df3vt.so' file to a suitable location and
amend your '~/.sqliterc' file if necessary.

usage example, using the sqlite3 shell:

  sqlite> .header on
  sqlite> .load df3vt
  sqlite> CREATE VIRTUAL TABLE df3 USING
     ...> df3vt(file='spiral.df3', readonly='yes');
  sqlite> SELECT * FROM df3 WHERE z = 2;
  x	y	z	v
  0	0	2	0
  1	0	2	0
  <<<<<<snip>>>>>>> 
  sqlite>

this version (0.1.2) is an update which implements SQL UPDATE for
the voxel value ('v') column.

the "ORDER BY" clause handling (indexing) is not yet implemented.

if, on loading, sqlite3 displays an "error during initialization",
the cause (likely) is a library version mismatch; df3vt requires
version 3.8.7 or later.

if the argument to 'readonly' is an unreasonably long string
(1023+ chars), an internal fixed-size  buffer will overflow.

see the comments at the top of the source file for the details.

(*) the extension should compile cleanly on Windows too, however,
since df3vt, like all df3 tools, expects file names to be POSIX.1
compliant, you cannot use a drive letter, backslashes, spaces, etc.

enjoy, jr.

