GNU 3DLDF

This copyright notice applies to the text and source code of this web site, and the graphic that appears on it. The software described in this text has its own copyright notice and license, which can be found in the distribution itself.

Permission is granted to copy, distribute, and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of this license is included in the file COPYING.TXT

Last updated: February 23, 2004.

[Epicycloid].

Late Breaking News

2004-02-23. I've had to revise my plans for the input routine. I believe it will now take months or years rather than weeks. I believe it will be possible to get very close to simulating the Metafont language, so I want to try to do that rather than releasing a cheap knock-off version. I do plan to release 3DLDF 1.2.0 when I've got the rules for declaring variables working, though. So I'm afraid 3DLDF users will have to put up with constantly recompiling and relinking for some time to come. See Coming later for more information.

GNU 3DLDF Version 1.1.5.1

GNU 3DLDF is a package for three-dimensional drawing with MetaPost output. It is intended, among other things, to provide a convenient way of creating 3D graphics for inclusion in TeX documents

It is written in C++ using CWEB. 3DLDF does not currently have an input routine, so user code must be written in C++, compiled, and linked with the rest of the program. Please don't be put off by this! It is true that users of 3DLDF must have at least a working knowledge of CWEB, C++, and MetaPost. However, I do try to make learning to 3DLDF as painless as possible. See the 3DLDF User and Reference Manual , for more information.

Writing an input routine is one of my top priorities and I've started work on it. When it's finished, 3DLDF should behave similarly to TeX, Metafont, and MetaPost from the point of view of a user. See Coming soon for more information.

2004-01-16. 3DLDF 1.1.5.1 Released.

In this release I correct a couple of minor problems I discovered in release 1.1.5:

A couple of Texinfo files for the 3DLDF User and Reference Manual were missing from the distribution of release 1.1.5. They are now included.

I've changed the names of the PNG (Portable Network Graphics) files included in the HTML version of the 3DLDF User and Reference Manual . I've also changed the names in the commands for including these files in the Texinfo files. I wasn't able to write some of the files with the old names to a CD-R (Compact Disk, Recordable). MS-DOS-incompatibility strikes again!

Distribution

3DLDF is now a GNU package, and the official 3DLDF website is www.gnu.org/software/3dldf/ , (which may not yet be available). See also http://www.gnu.org/directory/graphics/3D/3DLDF.html , which at least exists.

The official site for downloading 3DLDF is http://ftp.gnu.org/gnu/3dldf , but I will continue to make it available here.

The complete 3DLDF-1.1.5.1 distribution: 3DLDF-1.1.5.1.tar.gz

Other sites for downloading:

http://ftp.gwdg.de/pub/gnu2/3dldf

ftp://ftp.gwdg.de/pub/gnu2/3dldf

rsync://ftp.gwdg.de/pub/gnu2/3dldf (not clickable!)

http://dante.ctan.org/CTAN/graphics/3DLDF/

Documentation

The downloadable versions of 3DLDF: The Program, and the versions in the distribution have the table of contents at the front. This is not the case, if you generate them yourself. In order to do this, I used dviselect and dviconcat. I have not yet written make rules to do have this done automatically.

The 3DLDF User and Reference Manual , Edition 1.1.5.1, as an HTML document suitable for browsing, with one webpage per node.

The 3DLDF User and Reference Manual , Edition 1.1.5.1, as an HTML document suitable for browsing, entirely on one webpage.

The 3DLDF User and Reference Manual , Edition 1.1.5.1 in HTML format, with one webpage per node, as a compressed archive file (gzipped tar file) for downloading.

The 3DLDF User and Reference Manual , Edition 1.1.5.1 in HTML format, entirely on one webpage, as a compressed (gzipped) file for downloading.

The 3DLDF User and Reference Manual , Edition 1.1.5.1, as a compressed (gzipped) PostScript file for downloading.

The 3DLDF User and Reference Manual , Edition 1.1.5.1, as a compressed (gzipped) PDF (Portable Document Format) file for downloading.

3DLDF: The Program for version 1.1.5.1 as a compressed (gzipped) PostScript file.

3DLDF: The Program for version 1.1.5.1 as a compressed (gzipped) DVI file.

3DLDF: The Program for version 1.1.5.1 as a compressed (gzipped) PDF file.

I hope that the HTML version of the 3DLDF User and Reference Manual will be made available at http://www.gnu.org/software/3dldf/manual/ soon.

Patches

Patch instructions

Since 3DLDF 1.1.5.1 is being released so soon after 3DLDF 1.1.5, I'm supplying two patch files: 3DLDF-1.1.4-1.1.5.1.diff.gz and 3DLDF-1.1.5-1.1.5.1.diff.gz.

The following instructions are for applying the patch file 3DLDF-1.1.4-1.1.5.1.diff.gz to the directory 3DLDF-1.1.4.

The following instructions explain how to use 3DLDF-1.1.4-1.1.5.1.diff.gz to update 3DLDF 1.1.4. They apply equally to 3DLDF 1.1.5, except where noted, as long as the names of the files and diretories are changed appropriately.

The best way to apply the patch 3DLDF-1.1.4-1.1.5.1.diff.gz is to put the distribution of 3DLDF 1.1.4 in a new directory, e.g., 3DLDF-1.1.4. You may want you create a distribution by calling make dist from a shell in the working directory 3DLDF-1.1.4/. Then you will have to uncompress and expand 3DLDF-1.1.4.tar.gz:

gunzip 3DLDF-1.1.4.tar.gz
tar pxvf 3DLDF-1.1.4.tar

If you choose to use your existing 3DLDF-1.1.4 directory instead, you should save any files you don't want changed in a safe place.

Delete the directory 3DLDF-1.1.4/DOC/TEXINFO/EPS (not if you're patching 3DLDF 1.1.5!):

rm -rf 3DLDF-1.1.4/DOC/TEXINFO/EPS

This directory doesn't exist in 3DLDF 1.1.5 and 3DLDF 1.1.5.1. Instead, the illustrations for the Texinfo manual are in 3DLDF-1.1.5.1/DOC/TEXINFO/graphics/eps (for the PostScript version) and 3DLDF-1.1.5.1/DOC/TEXINFO/graphics/png (for the HTML version).

Please note that the HTML version of the Texinfo manual is not part of the distribution. It is, however, downloadable separately from my website and the GWDG server, so there should be no need to generate it yourself. See Distribution, above, for the URLs (Uniform Resource Locators).

Rename 3DLDF-1.1.4 3DLDF-1.1.5.1

mv 3DLDF-1.1.4 3DLDF-1.1.5.1

Now, put 3DLDF-1.1.4-1.1.5.1.diff.gz in 3DLDF-1.1.5.1. Change the working directory to 3DLDF-1.1.5.1 and unpack 3DLDF-1.1.4-1.1.5.1.diff.gz:

mv 3DLDF-1.1.4-1.1.5.1.diff.gz 3DLDF-1.1.5.1/ cd 3DLDF-1.1.5.1 gunzip 3DLDF-1.1.4-1.1.5.1.diff.gz

Apply the patch:

patch -p1 -i 3DLDF-1.1.4-1.1.5.1.diff

3DLDF-1.1.3-1.1.4.diff.gz

3DLDF-1.1.4-1.1.5.diff.gz

3DLDF-1.1.4-1.1.5.1.diff.gz

3DLDF-1.1.5-1.1.5.1.diff.gz

New in version 1.1.5

See Changes in the 3DLDF User and Reference Manual.

Coming soon

Coming later

2004-02-23.

At the present time, I don't have as much time to work on 3DLDF as I'd like; mainly because I have to look for a job. I've also started work on a couple of features that will take a long time to implement.

I am currently working on the input routine. I'm using Flex for the scanner and Bison for the parser. I've got the basic framework working, but there are a lot of rules to write. See Late Breaking News for more information.

I've started looking into rendering a bit more seriously. While I always want 3DLDF to be able to produce MetaPost output, I now believe that the best way of solving the problems of surface hiding, shading, and reflections is to use a different output format. I've started reading up on the PNG format . While I've found several free rendering packages, I haven't found one that does what I want and is adequately documented. Therefore, I've decided to implement rendering functionality within 3DLDF itself.

I'm also planning to change the way Pictures are output, so that this is done asynchronously. This will cause user-visible changes!

Currently, users must always call Picture::output() explicitly. I may change this behavior. I plan to change current_picture from a Picture to a pointer to Picture. beginfig() will allocate memory for a new Picture and point current_picture at it, and endfig() will call current_picture->output(). I may change endfig() so that it takes arguments and passes them to Picture::output(), or overload the current version of endfig() with one that does. Alternatively, I could put the arguments to endfig() into a struct and pass them to Picture::output() that way.

See also Future Plans in the 3DLDF User and Reference Manual.

Mailing lists

The following mailing lists are planned, but not yet available:
bug-3dldf@gnu.org for bug reports.
info-3dldf@gnu.org for sending announcements to users.
help-3dldf@gnu.org for users to ask one another for help.

Until they are, users can send an email with subscribe 3dldf [email-address] in the subject line to me at lfinsto1@gwdg.de
If the email-address is left out, I'll use the Reply-To of the email. If there's no Reply-To address, I'll use the From address. When info-3dldf@gnu.org is made available, I'll change the subscription to it.

Feedback

So far, I've had very little feedback about 3DLDF, so (constructive) comments and/or questions would be very welcome. I'd be particularly interested in knowing what people are using 3DLDF for. I think it would be nice to set up a Gallery on this website with artwork done with 3DLDF.

Volunteering

I've reached a point with 3DLDF where I can't do everything I want to myself, at least not as quickly as I'd like. Therefore, I would be very interested in finding other programmers who'd like to work on it with me.

Since 3DLDF is GNU software, I must exchange copyright papers with the authors before I accept any contributions of code or documentation. Contributions must also comply with the GNU Coding Standards. These restrictions are designed to protect the rights of those involved, and to ensure that 3DLDF remains free software .

I am particularly interested in help with the following tasks:

1. Porting to other architectures.

2. Programming functions for finding the intersections of plane geometric figures.

3. Improving the functions for constructing polyhedra.

4. Implementing an input routine using Flex and Bison.

5. Writing routines for interfacing with modelling and/or rendering software.

However, if you have another idea you'd like to implement, I'd be interested in hearing about it.

Errata and Addenda

File Permissions

I've now put the release versions of the files in 3DLDF under version control using RCS. This has significant advantages, but has the unpleasant effect of making some or all of the files in the distribution read-only, unless I've checked them out before calling make dist. On Unix-like systems, file permissions are changed using chmod. For example,
chmod u+w foo.web
makes foo.web writable for the user.

The dist target is generated automatically by Automake, and I don't know how to make it change the permissions to read-write. So users will have to reset the permissions themselves. Please let me know if you have problems: lfinsto1@gwdg.de

Bug fix: Rebuilding

Version 1.1.3 contains a bug fix that affected the files 3DLDF-1.1.2/CWEB/Makefile.am and 3DLDF-1.1.2/CWEB/tsthdweb. (Version 1.1.4 contains an additional bug fix as mentioned in New above. See also Late Breaking News.) Now, retangling, recompilation, and relinking should work properly. It was tricky to fix this, though, so problems might still arise. Please let me know if they do.

The bug fix involved changing the targets in 3DLDF-1.1.3/CWEB/Makefile.am for building the executable 3dldf. The shell script 3DLDF-1.1.3/CWEB/tsthdweb has also been changed, and it is now called differently in 3DLDF-1.1.3/CWEB/Makefile.am.

If only TeX text, comments, or whitespace in the CWEB file are changed, then no recompilation or relinking takes place, and the CWEB file isn't retangled the next time make 3dldf is called. Unfortunately, whitespace in literal strings that are part of the C++ code are also ignored, contrary to what I wrote in 3DLDF-1.1.3/CWEB/ChangeLog. It's not likely that this will cause any problems in actual use, though.

If only the C++ code has changed, the .cxx file is recompiled, and 3dldf is relinked.

If the header file has changed, all of the C++ files that depend on it are recompiled, and 3dldf is relinked.

Previously, a timer file was used for keeping track of whether <filename>.h had changed. Now, a second timer is used for keeping track of whether <filename>.cxx has changed. (Insert pun about two-timing here, when I've thought of one.)

The procedure seems to work when multiple files are changed in various ways. However, one unpleasant consequence is that the CWEB file must be touched to give it an earlier timestamp in the case that neither the C++ file nor the header file has changed (but only in this case!). This means that the file has changed on disk, so that the buffer must be reverted, if the user is currently working on it, which is likely. This shell script prints a message to this effect to standard output. This is annoying, but I haven't thought of a way around this problem. It's a consequence of using the timestamps of files to decide whether they need to be reprocessed. The best solution may be to return to using an auxilliary program for controlling recompilation. However, this will mean maintaining two different methods of rebuilding, because Automake requires valid build rules.

Reverting Buffers

If you're using Emacs, you can set a key to revert the buffer without querying by putting the following sexp (s-expression, but I don't know what s stands for) into your .emacs file:

(global-set-key [f5] '(lambda () (interactive) (revert-buffer t t)))

Or, if you're using, for example, foo mode, you can put the following sexp into your foo-mode-hook declaration:

(local-set-key foo-mode-map [f5] '(lambda () (interactive) (revert-buffer t t)))

For example,

(setq lisp-mode-hook '(lambda () (local-set-key [f5] '(lambda () (interactive) (revert-buffer t t)))))

Or, if you've defined a foo mode yourself, you can put the key assignment into foo-mode-map:

(if foo-mode-map ()
(setq foo-mode-map (nconc (make-sparse-keymap) c-mode-map))
;; else
(define-key foo-mode-map [f5] '(lambda () (interactive) (revert-buffer t t))))

Copyright Notice

Contact

If you want to contact me about 3DLDF, please put 3DLDF or something informative in the subject line of your email, so I won't think it's spam and delete it. I think I may have done this a couple of times. I'm sorry if it was your email.

If you want to encrypt an email to me, you can use my public key .

Laurence Finston
Kreuzbergring 41
D-37075 Göttingen
Germany
email: lfinsto1@gwdg.de
s246794@stud.uni-goettingen.de