This page contains more information
than you'll probably need to read. If you follow the
QuickStart instructions below, try using gifscroll immediately.
If you need more information,
continue reading until you feel comfortable trying to use gifscroll.
Return to this page as needed.
Prerequisites are: some knowledge of installing and using cgi
programs. &quotComputers are like Old Testament gods:
lots of rules and no mercy.&quot
Joseph Campbell, The Power of Myth
(Doubleday 1988, page 18)

C o n t e n t s

Q u i c k S t a r t ( the
problem with instant gratification
is that it takes too long
)

To see the simple scrolling banner, message=Hello, world. in your html page, just write the tag <img src="/cgi-bin/gifscroll.cgi?
message=Hello, world.">

To see the same banner with a simple additional effect, message=Hello, world.&nchkfg=4 write the same tag with the additional query string attribute <img src="/cgi-bin/gifscroll.cgi?message=Hello, world.
& nchkfg=4">

(1) Introduction

Gifscroll, licensed under
the GPL, is a
CGI
program written in C that renders
animated gif's representing scrolling led signs.
You can alternatively think of gifscroll as an elaborate version of
marquee tags.
Such elaborate scrolling led signs are
typically used as dedicated store window displays.
Gifscroll can be similarly used for that purpose with any spare display,
but is primarily intended for decorative banners
rendered on your html pages.

Gifscroll's html usage
is as simple as possible, with an <img> tag
containing a src= attribute that
executes gifscroll.cgi along with
a ?query_string
whose attribute=value pairs
describe the scrolling banner you want rendered. For example,

lets you simply write
<?php gifscroll("message=This is a test.&nflicker=4"); ?>
for the same result.

Physical hardware-based store window scrolling led signs,
which can cost thousands of dollars, like those sold by U.S. Distributor of LED Signs
provided the inspiration for programming gifscroll,
which costs nothing and runs on any existing
computer and display. Note: Scroll down to the bottom of that page
for a link to the
"Instruction Manual"
for their hardware-based signs,
which illustrates ideas for many different scrolling-banner effects,
and you may also want to see their
"Photo Gallery".

You can also find similar existing software-based solutions like SignBotFlashVortexMasterGreetingsAnimated Gif Led Signs
Gifscroll uniquely lets you generate signs on-the-fly,
using <img> tags embedded in your html pages.
And gifscroll provides various effects not provided by the others.
Conversely, some of the others provide effects not
currently available with gifscroll, although (if I do say
so myself:) gifscroll is currently perhaps the most elaborate
such program. And it's not clear to me why: maybe there's
just not much demand for such programs, or else
this little market niche has been overlooked and underserved.
The existence of expensive hardware-based signs suggests that
"not much demand" isn't the answer, which further
suggests that gifscroll may just be the first among many
more elaborate software-based solutions to follow it in the future.
Meanwhile, enjoy gifscroll today.

Dependencies

Gifscroll is based on two
of my other programs:gifsave89
to generate animated gif's, and
mimetex
to create rasterized bitmaps of messages you want displayed
on your banners. Copies of gifsave89.c and mimetex.c
(and two header files needed to compile mimetex)
are already included in your
gifscroll.zip
distribution. Nothing else is needed to compile and run gifscroll.

Source Code

File gifscroll.c contains all functions and header
information comprising gifscroll. The ultimate intent is to provide
a framework in which other programmers can add features and effects
in a reasonably straightforward fashion. But the current codebase
is more accurately described as a prototype (rather than a framework).
It's largely a "hodge-podge" of spaghetti-code, cobbled together
just to illustrate ideas and the feasibility of their implementaion.
Eventually, the accumulation of features will allow me
(or others) to step back, take a higher-level look over a large
enough landscape of functionality, and figure
out how to refactor the "hodge-podge" into a sensible framework
that can more easily accommodate forseeable future ideas.
In the meantime, if you're bold enough to try figuring out what
I'm doing, just continue the "bags-on-bags" development process
I've already fallen into. I don't think refactoring/redesign
is warranted at this time -- not until further experience
with the prototype reveals an underlying and more desirable
"big picture".

(2) Usage Summary

The Quickstart Section above
illustrates a few very simple usage examples, and the
Reference Section below
documents all gifscroll attributes and illustrates their behavior
(which is why this page takes so long to load:).
Here, we further introduce the basics, in somewhat more detail
than the Quickstart.
While not as detailed as the Reference,
this section may provide enough information to generate
all the scrolling banners you want, in which case you needn't bother
reading further.

Gifscroll typically runs as a
CGI
program after you've installed it
in the cgi-bin/ directory on your server.
And then your html pages access it to display scrolling banners
with <img> tags of the following form

Now just browse the examples below, choose any combination of effects
you like, and construct a ?query_string containing
the corresponding combination of attribute=value
pairs for those effects.
There's a pretty good chance that will "just work",
in which case (to repeat myself) you needn't bother reading any further.

nzoom = #times to zoom (shrink/enlarge)
during one full scroll of message,
default=0 (no zooming)
note: either a message or a pbmfile (see
below) may be zoom'ed zoomn = #steps to zoom (shrink and
re-enlarge) during each zoom
default=6 (if nzoom>0)
note: if zoomn<0, its abs() is used
and foreground color is randomized
for each step of each zoom zoomf = fraction 0<zoomf<1 to shrink
during each zoom step (1,...,zoomn),
default=0.9 (if nzoom>0)
note: total zoom = zoomf^zoomn,
must remain >0.01

fgoutline = color index(es) for outlining
message characters, pbmfile images, etc.
If several color indexes, e.g., fgoutline=1,2,3
(up to 9) are given, then several bands of color
outline characters/images.
(default=-999, no outlining,
also fgoutline=1 (black), 2=red, etc.) noutline = outline thickness in pixels (of each
color band, if several)
make sure there's adequate
margin
to accommodate total additional height,width
(of all bands, if several)
if noutline negative,
then its positive value is used, and...o if one band,
outlining "blinks" on-and-off o if several bands,
color bands "rotate" position
(default 2) margin = extra number of pixels, in height and
in width, surrounding your message
(if you have any border, this extra space is
between your message and that border).

utheta = instead of scrolling (when
nscroll=0), or even in addition
to scrolling (when nscroll>0),
#degrees to rotate image during each
frame (nframes not required when
nscroll=0 and utheta given) uaxis = default uaxis=1,0,0 rotates around
x-axis, or 0,1,0 around y-axis, or 0,0,1
around z-axis. Also, uaxis=1,1,0
rotates around diagonal axis, etc.

mtheta = similar idea to utheta
above, but rotates each character
of the message individually
(can't be used with pbmfile,
and you must supply a message) maxis = default maxis=0,1,0 rotates
around y-axis. (Other options
not yet available, and the
maxis attribute is ignored.)

splice = second message, or pbmfile
(must be used in conjunction
with utheta, see above) stype = 1(default):message, or 2:pbmfile utheta0 = theta for first frame,
90 and 270 are "splice points",
or any odd-number multiple of 90. uthetaspl = theta where original
replaced by splice, should be
>utheta0 and also a "splice point" uthetatot = total #degrees for banner,
should be >uthetaspl
and also a "splice point"

&stage=1 or &stage=2
(must be written with no intervening spaces)
first completes the banner generated by
the attributes specified before &stage,
and then follows it with the banner generated by
replacing some (stage=1) or all (stage=2)
of the original attributes with those
following &stage Note: You'll have to read the detailed &stage
documentation below
to get an effective sense of how to use it.

Note: The &stage=2 example on the right
retains the utheta=5 attribute, and would
have retained nscroll=0 had it not been
specified again.

when using utheta ... ptheta = degrees at which animation pauses,
typically chosen as 360,
and then a pause occurs at every
multiple of ptheta (e.g.,360,720,etc) pframes = each pause repeats that frame this #times
(default 0 for no pause) Notes: Checkerboarding and other effects >>except outlines and floating balloons<<
are turned off during paused frames,
as illustrated by the elaborate example.
This gives you time to read the message
without (too much) decoration.

Note: The following complicated example reproduces
my logo displayed in the upper-left corner
of this page,
using many of the attributes discussed above...

To compile a Unix/Linux executable, just type the following
command from the Unix shell cc O3
gifscroll.c gifsave89.c mimetex.c
lm o gifscroll.cgi
If you're compiling a Windows executable, then
add DWINDOWS . For example, cc DWINDOWS
gifscroll.c gifsave89.c mimetex.c
lm o gifscroll.exe
The above Unix-like syntax works with
MinGW and
djgpp
Windows compilers, but probably not with most others,
where it's only intended as a "template".
Explanation: gifscroll writes gif bytes directly to stdout, as usual
for cgi's. But Windows treats stdout as a character stream,
interpreting any hex 0A byte as an <lf>, and automatically
preceding it with a spurious hex 0D <cr> byte. The
DWINDOWS switch compiles in a non-portable, Windows-specific
_setmode() call that sets stdout to binary mode.

Optional additional compile D switches:

DREFERER=\"comma,separated,list\"
Once you've
installed gifscroll.cgi
on your web server, anybody can access it as a
public web service, which you likely may not want.
In that case, compile gifscroll as cc DREFERER=\"yourdomain\"
gifscroll.c gifsave89.c lm o gifscroll.cgi
Then gifscroll accepts requests only if the HTTP_REFERER
contains the string yourdomain as a substring.
If you want to grant gifscroll access to several domains, then cc DREFERER=\"domain1,domain2,etc\"
gifscroll.c gifsave89.c lm o gifscroll.cgi
Then requests are accepted only if the HTTP_REFERER
contains either domain1 or domain2, etc
as a substring.

DPASSWORD=\"pwdstring\"
If the preceding DREFERER
switch is given, then requests from invalid HTTP_REFERER's
are ignored, except if their query_string
contains the additional attribute password=pwdstring
with the correct password. That is, DPASSWORD is a
"backdoor" to access your gifscroll.cgi web service.
It's most typically useful if you want to enter requests directly
from a browser's url address bar, in which case
gifscroll sees no HTTP_REFERER at all.
And that's considered invalid if gifscroll's been compiled
with a DREFERER list, so DPASSWORD
is a way around that.

(3b) Test gifscroll

Before installinggifscroll.cgi,
you can test it from your shell's command line, as follows.
Just type, ./gifscroll.cgi
"message=testing&nchkfg=3"
or any similar query_string you like, between
"..." quotes. That should produce output
file gifscrolltest.gif, which you can view in your
browser, or in any gif viewer capable of rendering
animated gif's. If it looks okay, then you're good to go.
(Note that any backslashes in your "..."query_string will likely have to be escaped, as
per your shell's conventions.)

And also note that you can use gifscroll's command-line mode
for production purposes as well. Just generate the scrolling
banner(s) you want, and then rename it(them), e.g., mv
gifscrolltest.gif mybanner.gif
and then copy mybanner.gif to your website,
where a tag like <img src="mybanner.gif">
will display it. This way, there's no need to install
gifscroll.cgi directly on your site, and you can
ignore the next step.

(3c) Install gifscroll

You'll typically want the gifscroll.cgi executable image,
that you produced in the compile step above,
to be installed in your cgi-bin/ directory. First, make
sure to chmod 755
gifscroll.cgi
(or whatever other permissions your webserver may require),
and then just mv gifscroll.cgi to your cgi-bin/
directory.

There's one more thing you need to do. Generating scrolling
banners is somewhat compute intensive, so gifscroll caches
the images it renders, and just emits those cached images
whenever it's called with a duplicate query_string.
The cache directory is always called gifscroll/,
and always in the same directory as gifscroll.cgi.
So just mkdir cgi-bin/gifscroll/, or make the
cache directory anywhere you prefer, and put a symlink to it
in your cgi-bin/ directory. And now you're done.

(4) Gifscroll Reference

This section exhaustively discusses each attribute recognized
by gifscroll. Attributes are presented roughly in order by
"importance", though that's more of a personal judgment call.
Contents above presents an
alphabetical list, navigating you to each attribute in that order,
in case you have any trouble finding what you're looking for this way.

message

which renders the scrolling banner you've already
seen so many times above that I won't bother reproducing it yet again
here. But what's important to discuss in somewhat more detail here is the
markup syntax recognized by gifscroll messages. That's fully discussed
by the Syntax Reference Section of
mimeTeX,
which is the program gifscroll uses to get rasterized bitmaps of your messages.
Here we'll more briefly highlight several fragments of this syntax
particularly relevant for typical gifscroll messages.

Linebreaks:
For multiple-line banners, you'll need to specify a
linebreak/newline character in your message. Different markups
sometimes specify linebreaks in different ways. One typical way
is by \\ double-backslash, but that can
sometimes be mis-interpreted as escapes by shells, by browsers, etc.
So gifscroll recognizes <br> like html markup.
Thus,

message=This<br>is<br>a test.

renders...

To center lines, one above another, use
\center{line 1<br>line 2}
as in,

message=
\center{This<br>is<br>a<br>test.}

renders...

The enclosing { } braces
are necessary for internal reasons we needn't discuss.

Whitespace:
You can just press the spacebar multiple times to insert a corresponding
amount of additional whitespace, just like you'd expect. But note that
whitespace at the very beginning and very end of your message is
trimmed by gifscroll's querystring parser. What's also available for
whitespace anywhere in your message, and which won't be trimmed from
the beginning or end, is \hspace{n}
where n specifies the number of pixels of whitespace
you want at that point. For example,

\HUGE is gifscroll's default.
Still not large enough?:) Larger might actually
be reasonable if, for example, you're using gifscroll on a spare monitor
for a store window display, instead of buying a dedicated scrolling led sign.
In that kind of situation, mimeTeX provides \magstep{n},
where 1≤n≤10 is an integer between
1 and 10, and magnifies the size of all
characters by that number. Thus,

message=\HUGE\magstep{3}Testing

renders...

I won't display any larger \magstep's
here. They get kind of big. By the way, you're probably noticing
some antialiasing "staircasing" here. That'll be
even less noticeable on scrolling banners (and in any case,
not much I can easily do about it). For more detailed information,
Font Sizes contains a complete discussion.

Fonts:
mimeTeX has several fonts besides gifscroll's default
\text font.
mimeTeX Fonts contains a complete discussion.
Begin your message with \mathbb, etc, as illustrated
in the table below, to render the corresponding font.
And several additional fonts, and many symbols, not illustrated
in the table, are also available, as discussed in
mimeTeX Fonts.

Miscellaneous: Syntax Reference is a detailed discussion of the markup
recognized by gifscroll messages. Several features,
like \fbox{ } briefly alluded to above,
may prove useful or decorative, etc. For example,

message=\fbox{This is a test.}

message=\fbox{\fbox{This is a test.}}

renders...

It's hard for me to anticipate what features
you might find useful or decorative or frivolous, although gifscroll
is itself arguably pretty frivolous to begin with, beyond any
decorative value it may add to your web pages. All in the eye
of the beholder.

pbmfile

Instead of the message attribute
discussed above, gifscroll can generate a scrolling animation
of pretty much any image saved as a
P1 .pbm file. Moreover, you can usually reformat any graphic
image as a P1 .pbm using
ImageMagick convert. For example, if you already have a png
image, then

convert -compress none imagefile.png imagefile.pbm

outputs an uncompressed P1 .pbm black&white
bitmap file representing the same image. And you can simultaneously
apply other convert effects. For example,

convert -compress none -resize 200x300
imagefile.png imagefile.pbm

also resizes your original png image to 200x300
pixels, which may be more appropriate for a scrolling banner
(note that if you want to "resize" a pdf file, then -density
is the -switch to use).

You may be tempted to convert a multi-colored image to the
black&white foreground/background
P1 format required by gifscroll, which it uses as a mask.
That may or may not yield acceptable-looking results.
Monochrome images are best.

pbmf

If you haven't used
convert's
-resize (or -density) -switch, as described
immediately above, or maybe haven't used convert at all to obtain your
P1 .pbm file, you may still want to resize an existing image
for your gifscroll banners. The attribute pbmf=0.nnn where
0.0<0.nnn<1.0 is a number greater than 0.0
and less than 1.0, shrinks images to that fraction of their
original size (pbmf can't enlarge images).
Using my ubiquitous "jf-logo" as an example,

nscroll

This simply specifies the number of pixels per frame
to scroll your banner, left or right. Positive values scroll left,
negative values scroll right, default is nscroll=3 .
Gifscroll renders the number of frames necessary to scroll through
one complete cycle of your message, so that when your browser repeats
the gif, the message seamlessly repeats another scrolling cycle.

nframes

You may also specify nscroll=0 to inhibit horizontal
scrolling altogether. In that case you must also provide
the nframes=n attribute,
where n is any positive number specifying
the number of frames you want generated. If you specify both a
non-zero nscroll and also nframes,
then nframes are rendered, and your message may "jump" when
scrolling repeats.

delay

The delay=n attribute specifies
the delay in hundredths of a second (so delay=100
specifies one second) between the display of successive frames
of your animation. The default delay=0 in principle
tells your browser to display successive frames without delay.
But most browsers inhibit too-fast display, and typically
treat delay=0 and 1 (and sometimes
larger numbers) as 10. Below are a few examples
that may display differently on different browsers.
You may typically just ignore delay and let the
browser do what it thinks best, unless display timing
affects the look-and-feel you're trying to achieve.

(5) GPL License

&quotMy grandfather once told me there are two kinds of people:
&nbsp &nbsp Those who do the work and those who take the credit.
&nbsp &nbsp He told me to try to be in the first group; there was much
less competition.&quot
Indira Gandhi, the late Prime Minister of India

gifscroll's copyright is registered by me with the US Copyright Office,
and I hereby license it to you under the terms and conditions of the
GPL.
There is no official support of any kind whatsoever,
and you use gifscroll entirely at your own risk, with no guarantee
of any kind, in particular with no warranty of merchantability.

By using gifscroll, you warrant that you have read, understood
and agreed to these terms and conditions, and that you possess
the legal right and ability to enter into this agreement
and to use gifscroll in accordance with it.

Hopefully, the law and ethics regarding computer programs will
evolve to make this kind of obnoxious banter unnecessary.
In the meantime, please forgive me my paranoia.

To protect your own intellectual property, I recommend
Copyright Basics from The Library of Congress,
in particular Circular 61, Copyright Registration for
Computer Programs. Very briefly, download
Form TX
and follow the included instructions.
In principle, you automatically own the copyright
to anything you write the moment it's on paper. In practice,
if the matter comes under dispute, the courts look _very_ favorably
on you for demonstrating your intent by registering the copyright
_before_ infringement occurs.

(6) Concluding Remarks

&quotNostalgia isn't what it used to be.&quot Peter De Vries

I hope you find gifscroll useful. If so, a contribution to
the GNU project, is
suggested, especially if you're a company that's currently profitable.