@database arexx.guide
@author "Janne Jalkanen"
@(c) "Janne Jalkanen 1996"
@$VER: arexx.guide 1.3 (14.05.97)$

@wordwrap

@node Main "PPT Arexx interface"

                   @{fg highlight}THE AREXX INTERFACE@{fg text}


    No self-respecting Amiga program comes without Arexx port. So I've
    included one, too. Currently, there are not very many commands
    available, I'm afraid but the list is growing, day by day...

    This list is currently in alphabetical order.  A good idea might
    be to order them by context or something...  Tell me if you
    have a suggestion!

        @{" Generic hints " link Hints} - Read this!

        @{" ASKFILE     " link AskFile} - simple file requester
        @{" ASKREQ      " link AskReq} - complex requester construction

        @{" CLOSERENDER " link CloseRender} - closes a rendered image screen
        @{" COPYFRAME   " link CopyFrame} - makes a duplicate from a frame
        @{" CROP        " link Crop} - crops to the selected area

        @{" DELETEFRAME " link DeleteFrame} - removes a frame from memory

        @{" EFFECTINFO  " link EffectInfo} - information about an effect
        @{" FRAMEINFO   " link FrameInfo} - information about a frame

        @{" GETAREA     " link GetArea} - returns the selected area
        @{" GETRENDERPREFS " link GetRenderPrefs} - gets rendering preferences

        @{" LISTEFFECTS " link ListEffects} - returns a list of effects available
        @{" LISTIOMODULES " link ListLoaders} - returns a list of iomodules available
        @{" IOMODULEINFO  " link LoaderInfo} - returns info about an IO module
        @{" LOADFRAME   " link LoadFrame} - open a frame

        @{" PPT_TO_BACK " link PPTToBack} - sends PPT screen to back
        @{" PPT_TO_FRONT " link PPTToFront} - pops PPT screen to front
        @{" PROCESS     " link Process} - starts an effect

        @{" RENAMEFRAME " link RenameFrame} - renames a frame
        @{" RENDER      " link Render} - renders using current preferences
        @{" RENDER_TO_FRONT " link RenderToFront} - brings rendered image to front

        @{" SAVEFRAMEAS " link SaveFrameAs} - saves frame under a different name
        @{" SETAREA     " link SetArea} - set the selection area
        @{" SETRENDERPREFS " link SetRenderPrefs} - sets render preferences
        @{" SHOWERROR   " link ShowError} - show an error message

        @{" VERSION     " link Version} - give version information

        @{" QUIT        " link Quit} - quit PPT

@endnode

@node Hints "Generic hints on writing AREXX scripts for PPT"

@{b}Generic hints on writing AREXX scripts for PPT@{ub}

    Currently this section is a bit incomplete, but I suggest you still
    keep the following things in mind:

    · Some effects (Brightness, Contrast, and Gamma, for example) use
      floating point values for input.  While this is OK by AREXX, you
      might want to enclose numeric literals in quotes, when you send
      them to PPT.

    · Use the empty.prx script from the Rexx/ -directory as a template
      for your own scripts.  It contains error handlers to ease your
      job.

    · Be easy on quotes and double-quotes.  If you use too many of them,
      you'll probably start getting strange error messages from PPT.
      A good example might be "REXX message of incorrect format" which
      probably means you've overdosed on quotes.

@endnode

@node AskFile "AREXX: ASKFILE"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    TITLE/A,POSITIVE=POS,INITIALDRAWER=ID/K,INITIALFILE=IF/K,
    INITIALPATTERN=IP/K,SAVE/S

@{b}INPUTS@{ub}
    TITLE - The title for the requester
    POSITIVE - Whatever the positive gadget should say. Default is
        the default for the locale (English : "OK").
    INITIALDRAWER - The contents of the Drawer gadget. Default
        is to use the directory that the "Open..." file requester
        uses.
    INITIALFILE - The contents of the File gadget.
    INITIALPATTERN - The contents of the Pattern gadget.  If not
        specified, no pattern gadget will be displayed.
    SAVE - If set, then the requester will be a save requester
        (white text on black background).

@{b}OUTPUTS@{ub}
    RESULT = filename.
    RC ~= 0 on error, RC2 contains error message.

    If the user cancels, RC = 5.

@{b}DESCRIPTION@{ub}
    This is a multi-purpose interface to the  ASL  file  requester.  Its
    good side is that it actually remembers what you did last, so you do
    not have to specify all of the options each time.

    NB: The SAVE  and  INITIALPATTERN  are  not  remember  between  each
    invocation of this call. If you can convince me otherwise, do so...

@{b}EXAMPLE@{ub}

    ASKFILE '"Open file"'

    This asks the user for a file.  Nothing fancy there.

    ASKFILE '"Save file"' POS "Save!" ID="T:" SAVE

    Asks the user for a filename for  saving.  Default  directory  shown
    will be T:.

@{b}BUGS@{ub}
    Maybe more options?  Do you need more?  Write me, I will help!

@{b}SEE ALSO@{ub}

@endnode

@node AskReq "REXX: ASKREQ - build complex requesters"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    ASKREQ TEXT/A,POSITIVE=POS/K,NEGATIVE=NEG/K,GAD1,...

@{b}INPUTS@{ub}
    TEXT - A string to be shown in the text box at the top of the
        window.
    POSITIVE - Positive gadget (bottom left).  English default is "Ok".
    NEGATIVE - Negative gadget (bottom right). English default is "Cancel".
    GAD1 - The first of stems describing other gadgets on this requester.
        See below.

@{b}OUTPUTS@{ub}
    RESULT = 0, if the user OK'ed the requester, ~= 0 otherwise.
    RC ~= 0 on error.

@{b}DESCRIPTION@{ub}
    This is a command that allows building multiple-gadget requesters.
    The idea is that each of the gadgets on the requester is described
    by a stem, which contains the necessary details for the gadget
    to be displayed.  This is how you would create a simple gadget that
    would ask for values between -128 and +128:

    MYGAD.TYPE=SLIDER /* Because we want a slider gadget */
    MYGAD.MIN=-128    /* Minimum value that the slider should accept */
    MYGAD.MAX=128     /* Maximum value that the slider should accept */
    MYGAD.LABEL='"Slide me"' /* Label to appear on the left side of the slider */
    MYGAD.DEFAULT=0   /* Default value is zero */

    ASKREQ '"Select the new value for mygadget"' MYGAD

    IF result = 0 THEN DO
        ... /* Whatever you like */
    DONE
    ELSE DO
        ... /* Cancelled */
    DONE

    (Note the single and double quotes ('"..."') that are required for
    the text with spaces in it to pass the REXX parser without being
    chopped to pieces.)

    When ASKREQ is done, the value for each of the gadgets can be found
    in the stem variable .VALUE, ie. in the previous example the
    result could be read from MYGAD.VALUE.

    Common attributes for different gadgets are:

        .LABEL - this sets the label to be seen on the left side of the
            gadget.

    Different gadgets that ASKREQ recognizes are:

    .TYPE = SLIDER
        This produces a slider gadget that has an integer gadget  placed
        next to it. Possible attributes are:

        .MIN - The minimum value that is possible to be entered into
            this gadget.  Default is zero (0).
        .MAX - The maximum value.  Default is 100.
        .DEFAULT - The value the slider should start from. Default is 50.

        The result is returned in .VALUE, which contains the position of
        the slider (between .MIN and .MAX).

    .TYPE = CHECKBOX
        This  produces  a  simple  checkbox  (on/off  gadget).  Possible
        attributes are:

        .SELECTED - Set this to 1, if you want the gadget to be selected
            (ie. have a checkmark in it) initially. Default is zero.

        The result returned in the .VALUE is 0, if the  gadget  was  not
        checked or ~= 0, if the gadget was checked.

    .TYPE = STRING
        This produces a string (text entry) gadget. Possible  attributes
        are:

        .MAXCHARS - Maximum length of the string allowed.  Default is 80.
        .INITIALSTRING - A string that is used as the initial value for
            the gadget.  Default is "" (empty string).

        The result returned in the .VALUE-attribute is the  string  that
        the user entered into the gadget.

    .TYPE = CYCLE
        This produces a cycle gadget (or popup-menu, if  so  requested.)
        Possible attributes are:

        .ACTIVE - The initial active choice.  Zero (which is the default)
            means the first choice.
        .POPUP - Set this to 1, if you want a popup-menu style gadget.
            Default is 0 (a plain cycle gadget).
        .LABELS - A string of bar-separated words, that are the different
            choices available to the user.  For example:

            MYGAD.TYPE=CYCLE
            MYGAD.LABELS="One|Two|Three"

            would produce a cycle  gadget  that  has  three  choices  to
            choose from.

            Note that this attribute MUST  BE  SPECIFIED,  otherwise  an
            error will be returned.

        The result returned in .VALUE is the currently active choice  (0
        means the first choice).

    .TYPE = FLOAT
        This produces a floating point gadget with a slider attached.
        Possible attributes are:

        .MIN - The minimum value.  Default is 0.0.
        .MAX - The maximum value.  Default is 100.0.
        .DEFAULT - The initial value.  Default is 0.0.
        .FORMATSTRING - A standard C printf() format string for the
            gadget.  Default is "%.3f", i.e. show three decimals.

    Note that these names are case-insensitive as the rest of the AREXX.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    Example code in PROGDIR:rexx/

@endnode


@node CloseRender "AREXX: CLOSERENDER"

@{b}MENU@{ub}
    @{"Render/Close Render" link ppt.guide/CloseRender}

@{b}AREXX Command Template@{ub}
    CLOSERENDER FRAME/A/N

@{b}INPUTS@{ub}
    FRAME - frame id.

@{b}OUTPUTS@{ub}
    RC ~= 0 on error.

@{b}DESCRIPTION@{ub}
    This command closes a rendered image and frees the memory
    back to system use.  Note that it is safe to call this even
    when there is no rendered image.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"RENDER" link Render}

@endnode



@node CopyFrame "AREXX: COPYFRAME"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    COPYFRAME FRAME/A/N

@{b}INPUTS@{ub}
    FRAME = frame to be duplicated.

@{b}OUTPUTS@{ub}
    RC = 0, if succeeded
    RESULT = new frame id.

@{b}DESCRIPTION@{ub}
    Use this command to make a complete duplicate of a frame.  The only
    thing differing from the original frame is the name.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode



@node Crop "AREXX: CROP"

@{b}MENU@{ub}
    Edit/Crop

@{b}AREXX Command Template@{ub}
    CROP FRAME/A/N

@{b}INPUTS@{ub}
    FRAME = frame

@{b}OUTPUTS@{ub}
    A smaller frame

@{b}DESCRIPTION@{ub}
    Crops away the area outside the selected area.

    Use the SETAREA command to first set the area to be cropped!    

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@node LoadFrame "AREXX: LOADFRAME"

@{b}MENU@{ub}
    Project/Load

@{b}AREXX Command Template@{ub}
    LOADFRAME FILE/A

@{b}INPUTS@{ub}
    FILE = the file to be loaded.

@{b}OUTPUTS@{ub}
    rc = 0, if succeeded.
    RESULT = new frame id.

@{b}DESCRIPTION@{ub}
    Loads a new frame to the PPT.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"SAVEFRAMEAS" link SaveFrameAs}

@endnode



@node DeleteFrame "AREXX: DELETEFRAME"

@{b}MENU@{ub}
    Project/Delete

@{b}AREXX Command Template@{ub}
    DELETEFRAME FRAME/A/N,FORCE/S

@{b}INPUTS@{ub}
    FRAME - the frame ID.
    FORCE - If not specified, a confirmation requestor
        is shown.

@{b}OUTPUTS@{ub}
    A lot more free memory.

@{b}DESCRIPTION@{ub}
    Deletes the frame completely. No traces. You will be asked
    for a confirmation first, of course.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@remark ---------------------------------------------------------
@remark         AREXX Commands
@remark ---------------------------------------------------------

@node ListIOModules "AREXX: LISTIOMODULES"

@{b}MENU@{ub}
    Windows/Loaders

@{b}AREXX Command Template@{ub}
    LISTIOMODULES STEM/A,ONLYLOADERS/S,ONLYSAVERS/S

@{b}INPUTS@{ub}
    STEM - a variable to be filled with data.
        STEM.0 - amount of loaders
        STEM.1 - first loader name,
        STEM.2 - second loader name
        ...
    ONLYLOADERS - specify if you do not want to see any savers
    ONLYSAVERS - specify if you do not want to see any loaders

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    Returns available IO modules in the system. By  using  the  switches
    you may specify which kind of modules you want to see.

@{b}BUGS@{ub}
    The switches are not very clear.

@{b}SEE ALSO@{ub}
    @{ "LISTEFFECTS" link ListEffects }, @{"IOMODULEINFO" link IOModuleinfo}

@endnode

@node IOModuleInfo "AREXX: IOMODULEINFO"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    IOMODULEINFO IOMODULE/A,STEM/A

@{b}INPUTS@{ub}
    IOMODULE - The IO module name you wish info on.
    STEM - A stem variable telling where the info should be put.

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    Gets information on a given module. The stem is filled out as follows:
        STEM.VERSION - Version number
        STEM.REVISION - Revision number
        STEM.AUTHOR - The author of this module
        STEM.INFOTXT - A short blurb describing this module.
        STEM.LOAD - 1, if this module is capable of loading
        STEM.SAVETC - 1, if this module saves truecolor images
        STEM.SAVECM - 1, if this module saves colormapped images
        STEM.REXXTEMPLATE - String containing the AREXX command template
            for this module.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{ "EFFECTINFO" link EffectInfo}, @{ "LISTIOMODULES" link ListIOModules}.

@endnode


@node EffectInfo "AREXX: EFFECTINFO"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    EFFECTINFO EFFECT/A,STEM/A

@{b}INPUTS@{ub}
    EFFECT - The effect name you wish info on.
    STEM - A stem variable telling where the info should be put.

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    Gets information on a given effect. The stem is filled out as follows:
        STEM.VERSION - Version number
        STEM.REVISION - Revision number
        STEM.AUTHOR - The author of this module
        STEM.INFOTXT - A short blurb describing this module.
        STEM.REXXTEMPLATE - String containing the AREXX command template
            for this effect.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{ "IOMODULEINFO" link IOModuleInfo}, @{ "LISTEFFECTS" link ListEffects}.

@endnode


@node ListEffects "AREXX: LISTEFFECTS"

@{b}MENU@{ub}
    Project/Modules/Filters

@{b}AREXX Command Template@{ub}
    LISTEFFECTS STEM/A

@{b}INPUTS@{ub}
    STEM - specifies a stem variable to be affected. Hereforth
        referenced to as stem.

@{b}OUTPUTS@{ub}
    The stem.0 - compound symbol contains the number of possible
    effects. The names of the effects will be from compound
    symbol stem.1 onward.

@{b}DESCRIPTION@{ub}
    Use this to get a listing of all possible effects at your
    disposal.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"EFFECTINFO" link EffectInfo}, @{"LISTIOMODULES" link ListIOModules}.

@endnode


@node FrameInfo "AREXX: FRAMEINFO"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    FRAMEINFO FRAME/A/N,STEM/A

@{b}INPUTS@{ub}
    FRAME - frame ID
    STEM - a stem variable where the information is put.

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    The stem variable is filled as follows:
        STEM.NAME - The name for this frame
        STEM.FILENAME - The actual path for the file on disk.
        STEM.HEIGHT - Height of the image
        STEM.WIDTH - Width of the image
        STEM.COLORSPACE - A name describing the colorspace.  Possible
            results are "RGB", "Greyscale" and "ARGB".
        STEM.COMPONENTS - # of components / pixel.
        STEM.DPIX, STEM.DPIY - The Dots-Per-Inch figures for X
            and Y axis.  Also tells you the image aspect ratio.
        STEM.BYTESPERROW - How many bytes does one row occupy

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@node SetArea "AREXX: SETAREA"

@{b}MENU@{ub}
    NA

@{b}AREXX Command Template@{ub}
    SETAREA FRAME/A,X0/N,Y0/N,X1/N,Y1/N,ALL/S

@{b}INPUTS@{ub}
    FRAME  = frame name
    X0, Y0 = Co-ordinates of the upper left-hand corner
    X1, Y1 = Co-ordinates of the lower right-hand corner
    ALL    = Specify if you wish to select the whole picture

    If ALL is specified on the command line, the co-ordinates
    are ignored.

@{b}OUTPUTS@{ub}
    RC = 5, if the co-ordinates were out of bounds or there
    were not enough of them.

@{b}DESCRIPTION@{ub}
    Set the area to be used with processing applications.

@endnode


@node Quit "AREXX: QUIT"

@{b}MENU@{ub}
    @{"Project/Quit" link ppt.guide/quit} (Q)

@{b}AREXX Command Template@{ub}
    QUIT FORCE/S

@{b}INPUTS@{ub}
    Specify FORCE on the command line if you don't wish the selection
    to be confirmed.

@{b}OUTPUTS@{ub}
    RC = 5, if the user cancelled, 0 otherwise.

@{b}DESCRIPTION@{ub}
    You may quit the program by selecting this. You will be asked first for
    confirmation, of course, unless the FORCE - keyword is specified.

@endnode

@node PPTToFront "AREXX: PPT_TO_FRONT"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    PPT_TO_FRONT

@{b}INPUTS@{ub}
    N/A

@{b}OUTPUTS@{ub}
    N/A

@{b}DESCRIPTION@{ub}
    Brings the PPT screen to the front.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"PPT_TO_BACK" link PPTToBack},intuition.library/ScreenToFront()

@endnode


@node PPTToBack "AREXX: PPT_TO_BACK"

@{b}MENU@{ub}
    N/A, except for the little knob at the top of the screen.

@{b}AREXX Command Template@{ub}
    PPT_TO_BACK

@{b}INPUTS@{ub}
    N/A

@{b}OUTPUTS@{ub}
    N/A

@{b}DESCRIPTION@{ub}
    Pushes the PPT screen to be the backmost screen.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"PPT_TO_FRONT" link PPTToFront},intuition.library/ScreenToBack()

@endnode


@node Process "AREXX: PROCESS"

@{b}MENU@{ub}
    @{"Process/Process..." link ppt.guide/process}

@{b}AREXX Command Template@{ub}
    PROCESS FRAME/A/N EFFECT/A ARGS/F

@{b}INPUTS@{ub}
    FRAME  - frame id
    EFFECT - the name of the effect you wish to perform
    ARGS   - all the rest of the command line is understood as
             arguments for the effect. See @{"effects" link effects.guide/Main} for more
             information.

@{b}OUTPUTS@{ub}
    RC != 0 on error.
    RC2 = a textual description of the error.

@{b}DESCRIPTION@{ub}
    Start up a new process.  Note that this command is blocking, ie.
    even though a new process is started this command does not return
    until it has completed.  However, it does not block PPT and you
    may still run other Arexx scripts or use the program manually
    while this command is executing.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@node SaveFrameAs "AREXX: SAVEFRAMEAS"

@{b}MENU@{ub}
    @{"Project/Save As..." link ppt.guide/SaveAs}

@{b}AREXX Command Template@{ub}
    SAVEFRAMEAS FRAME/A/N FILENAME/A FORMAT/A/K COLORMAPPED/S ARGS/F

@{b}INPUTS@{ub}
    FRAME - frame id
    FILENAME - the new filename to save this frame as.
    FORMAT - the file format
    COLORMAPPED - if specified, will save the rendered image
        (you must use @{"RENDER" link Render} first!)
    ARGS - the rest of the line is used as parameters to be
        sent to the IO module.

@{b}OUTPUTS@{ub}
    RC != 0 on error.
    RC2 = a textual description of the error.

@{b}DESCRIPTION@{ub}
    Use this command to save a frame that has been loaded into PPT.
    I think it's easiest just to give an example:

    @{"LOADFRAME" link LoadFrame} "t:foo.ilbm"
    myframe = result
    SAVEFRAMEAS myframe "t:foo.jpg" FORMAT=JPEG COMPRESSIONLEVEL=50 PROGRESSIVE

    This command loads image "t:foo.ilbm" into PPT and saves it back
    as a JPEG image.

    Note that everything that has not been identified as a parameter
    to this command is passed to the IO module and thus you should look
    at the {"loaders.guide" link loaders.guide/main} to see what parameters
    different modules accept.

@{b}BUGS@{ub}
    May be a bit shaky at the moment.

@{b}SEE ALSO@{ub}
    @{"LOADFRAME" link LoadFrame}

@endnode

@node ShowError "REXX: SHOWERROR"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    SHOWERROR ERROR/A,LINE/N

@{b}INPUTS@{ub}
    ERROR - Error text.
    LINE - Optional line on which the error occurred.

@{b}OUTPUTS@{ub}
    N/A

@{b}DESCRIPTION@{ub}
    Shows a simple requester on the PPT screen informing the user
    that an error has occurred within the REXX script.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode



@node Render "AREXX: RENDER"

@{b}MENU@{ub}
    @{"Render/Render" link ppt.guide/Render}

@{b}AREXX Command Template@{ub}
    RENDER FRAME/A/N

@{b}INPUTS@{ub}
    FRAME - Frame id

@{b}OUTPUTS@{ub}
    RC != 0 on error.

@{b}DESCRIPTION@{ub}
    Renders the frame using the current preferences.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"SETRENDERPREFS" link SetRenderPrefs}

@endnode

@node RenderToFront "AREXX: RENDER_TO_FRONT"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    RENDER_TO_FRONT FRAME/A/N

@{b}INPUTS@{ub}
    FRAME - frame id

@{b}OUTPUTS@{ub}
    RC ~= 0 on error

@{b}DESCRIPTION@{ub}
    If a rendered image on a separate screen exists, this will
    bring it to the front.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode




@node SetRenderPrefs "AREXX: SETRENDERPREFS"

@{b}MENU@{ub}
    @{"Render/Settings..." link ppt.guide/RenderSettings}

@{b}AREXX Command Template@{ub}
    SETRENDERPREFS FRAME/A/N NCOLORS/K/N MODE/K DITHER/K MODEID/K/N
                   FORCEBW/S

@{b}INPUTS@{ub}
    FRAME - frame id
    NCOLORS - maximum number of colors that PPT is allowed to use
        (this also affects the number of base colors available in
        the HAM modes)
    MODE - The display mode: Color,EHB,HAM6 or HAM8
    DITHER - The dither to be used.  Available options are:
        None and Floyd-Steinberg
    MODEID - Standard Amiga ModeID for the screen.  In decimal, please.
    FORCEBW - Forces the background color to zero (black) and the
        foreground color (one) to white.

@{b}OUTPUTS@{ub}
    RC ~= 0 on error

@{b}DESCRIPTION@{ub}
    Set the render preferences for a frame.  Here's an example:

    SETRENDERPREFS myframe MODE HAM8 DITHER Floyd-Steinberg

    This makes the next render to use HAM8 with FS dithering.

@{b}BUGS@{ub}
    Modeid should be usable in hexadecimal and text too.
    DITHER should really understand about abbreviated names, too.

@{b}SEE ALSO@{ub}
    @{"GETRENDERPREFS" link GetRenderPrefs},
    @{"Render/Settings..." link ppt.guide/RenderSettings}

@endnode

@node GetRenderPrefs "AREXX: GETRENDERPREFS"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    GETRENDERPREFS FRAME/A/N PREFS/A

@{b}INPUTS@{ub}
    PREFS - a stem into which the preferences are put.

@{b}OUTPUTS@{ub}
    RC ~= 0 on error.

@{b}DESCRIPTION@{ub}
    The PREFS stem consists of following elements after the command
    has returned:

    MODEID  = current mode id
    DEPTH   = display depth
    NCOLORS = number of colors
    DITHER  = string telling the current dithering method
    MODE    = render mode (Normal, EHB, HAM6, HAM8)
    FORCEBW = 0, if Black/White color scheme for the two first
              colors is not used, ~= 0 otherwise.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"SETRENDERPREFS" link SetRenderPrefs},
    @{"Render/Settings..." link ppt.guide/RenderSettings}

@endnode


@node empty

@{b}MENU@{ub}

@{b}AREXX Command Template@{ub}

@{b}INPUTS@{ub}

@{b}OUTPUTS@{ub}

@{b}DESCRIPTION@{ub}

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode