Hwp_Plananarama

Plananarama
===========

The Plananarama plugin allows Hollywood to run on planar (palette-based)
screens. This finally
makes it possible to run Hollywood scripts on plain AGA or ECS systems with no
graphics board
installed - for the first time since Hollywood 1.93 (released in March 2005)!
Starting with
version 2.0, Hollywood required CyberGraphX or Picasso96 to run. Since then,
many people have
asked for a revival of Hollywood's planar engine, so here it is, a real blast
from the past!
Thanks to Hollywood 6's greatly extended plugin API this feature could be
implemented
completely in plugin space. Once Plananarama is installed, all Hollywood scripts
will magically
run on palette screens again! All resolutions are supported - from 8-bit LowRes
to 1-bit
productivity SuperHighRes Interlace.

This plugin was first created during the development of Hollywood 6.0 a
proof-of-concept for
the flexibility of Hollywood 6.0's powerful display and bitmap adapters. This
plugin completely
replaces Hollywood's default display adapter and installs a custom one that is
able to run on
planar screens. 


Requirements
============

This plugin requires at least Hollywood 6.0 since it uses the display and bitmap
adapter APIs
introduced with Hollywood 6.0.

Additionally, there are the following requirements:

- guigfx.library
- render.library (*)
- FBlit (**)
- some fast memory for FBlit

(*) Note that render.library is available in two flavours: The latest version is
v40.8. It is a
C port of the original render.library which was written in 68k assembler. The
assembler version
of render.library is much faster than the C version which is why you might want
to use the
assembler version instead. The latest assembler version of render.library is
v31.0. Plananarama
doesn't require v40, you can also use v31 if you care about performance.

(**) FBlit is not actually required but highly recommended because otherwise
your chip memory
will be gone in no time and Hollywood will run out of memory. So make sure you
install FBlit
first and you add Hollywood to its "Include" list in the "FAllocBitMap" tab. If
Hollywood is
included in this list, it will be able to place graphics in fast memory which is
absolutely
needed since 2 MB of chip memory certainly won't be enough for Hollywood. Using
FBlit also has
the advantage that Hollywood can use the CPU for blitting which is much faster
than the blitter
on higher 68k CPUs or WinUAE anyway.


Usage
=====

There are several ways to use this plugin: You can either activate the plugin
for a script by
()REQUIRE-ing it. To do this, simply put the following preprocessor command at
the top of your
script:

    ()REQUIRE "Plananarama"

Or you can use the REQUIREPLUGINS argument from the command line or set the
tooltype of the very
same name. This is the preferred method to use if you don't want to modify the
scripts you want
to run with Plananarama, maybe because they should only use Plananarama on
AmigaOS 3 systems but
on other systems they should run without it. Here is an example:

    1> Hollywood Hollywood:Examples/Hollywood/3DText/3DText.hws -requireplugins
plananarama
    
You can also use the REQUIREPLUGINS argument in the tooltypes. The tooltype
version would be:

    REQUIREPLUGINS=Plananarama

When using the Hollywood GUI, you can route every Hollywood script launched from
the GUI
through the Plananarama plugin, by going to the "Prefs/Hollywood..." menu and
entering
"-requireplugins plananarama" in the "Additional interpreter arguments" text
gadget.


Options
=======

Plananarama supports several options which can be passed to ()REQUIRE or to the
REQUIRETAGS
arguments. See the Hollywood documentation to learn how to pass parameters to
()REQUIRE and
REQUIRETAGS.

The following options are currently available:

DitherMode:
This can be "None", "FS" (the default), "Random", or "Edd". Here is a
description of the
different dither modes:
    "None"  : No dithering at all.    
    "FS"    : Floyd-Steinberg dithering. This is the default.
    "Random": Random dithering. This mode is significantly slower than
Floyd-Steinberg
              dithering.              
    "Edd"   : EDD dithering. This mode is faster than Floyd-Steinberg dithering.
    
DitherAmount:
Set the dither amount. This must be between 0 and 255. Currently this value is
of any
use only for the "Random" dither mode. Defaults to 40.

AutoDither:
Enable automatic dithering. If set to TRUE, dithering is automatically activated
for drawing
a particular picture to a particular environment, when the loss of color
information would
exceed a certain threshold (see below). Defaults to TRUE.

DitherThreshold:
The threshold for automatic dithering. The lower, the earlier automatic
dithering is activated.
Useful thresholds range between 10 and 10000. Refer to
render.library/RGBArrayDiversityA() for
further details. Better you do not use this tag unless you have a good reason
to. Let the user
customize it with the environment variable AUTODITHERTHRESHOLD. Defaults to 250.

Precision:
Set the precision for pen allocations. This can be "Exact", "Image" (the
default), "Icon", or
"GUI". See graphics.library/ObtainBestPenA() for details. Note that the default
precision
suffices for almost every application. Pens are obtained in an extremely
effective way. You
get excellent results even with lower precisions. Commodore's idea with
ObtainBestPenA() was
to create a fair and effective pen-sharing mechanism, and Plananarama behaves in
perfect
accordance to this intention. Never use insane patches for ObtainBestPenA(). 


Troubleshooting
===============

a) Plananarama says "Cannot open guigfx.library!" but I have guigfx.library
installed:

guigfx.library requires render.library and will fail to open in case
render.library isn't
present so make sure you have render.library as well. If you do, make sure you
have the
right version of render.library. Some require an FPU and will fail to open if no
FPU is
present.

b) My system crashes with a 8000000B software failure:

You are using a version of render.library that needs an FPU on a system without
an FPU.
Make sure to use the appropriate version for your system because some versions
of render.library
don't check if an FPU is present, they will just crash if there is none.

c) I'm getting an "Out of memory!" error but I have lots of fast memory.

First make sure you have installed FBlit. Then make sure that you've configured
FBlit correctly.
You have to add Hollywood to FBlit's "Include" list in the "FAllocBitMap" tab.
If Hollywood is
included in this list, it will be able to place graphics in fast memory which is
absolutely
needed since 2 MB of chip memory certainly won't be enough for Hollywood. So
make sure you
configure FBlit correctly.

d) Plananarama is very slow:

If Plananarama performs poorly on your system then the reason might be that your
script is
drawing many images with alpha channel graphics, e.g. anti-aliased text/shapes
or images with
variable levels of transparency. These things do not make much sense on
palette-based screens
and they are very, very expensive on the CPU because Plananarama needs to remap
these images
from true colour chunky pixels to planar graphics all the time.

Thus, if you care about performance you should not use any alpha channel images
and transparency
should be limited to monochrome transparency (i.e. visible and invisible
pixels). The best idea
is to use a fixed set of prerendered graphics. When just drawing prerendered
graphics with no
changes concerning the colors, Plananarama should perform quite well on planar
screens and
scripts should also be usable on slower systems, though you still need a fast
CPU and some fast
memory of course.


History
=======

Version 1.0:    (10-Jan-16)
- First release


Future
======

More optimizations.


Bugs
====

Please report any bugs or issues via the Hollywood forums at
http://forums.hollywood-mal.com/


Copyright
=========

This plugin is (C) Copyright 2014-2016 by Andreas Falkenhahn
<andreas()airsoftsoftwair.de>
Refer to the COPYING file in this package for conditions concerning distribution
of this plugin.
This plugin uses guigfx.library and render.library by Timm S. Müller. Parts of
this document
are based on the documentation of guigfx.library written by Timm S. Müller. For
support and more
plugins please visit http://www.hollywood-mal.com/.