@DATABASE Palette V1.10
$VER: Pure Basic - Palette library V1.00 (01.09.1999) © Fantaisie Software
@NODE MAIN "Palette V1.10"

  @{b}Pure Basic Palette library V1.00@{ub}

    Palette are very important for all displayed elements. There are
    very good supported and you can do almost everything you need.
    Special functions like very fast fading routines allow you
    to achieve very good effects.

  @{b}Commands summary:@{ub}

    @{" Blue              " LINK Blue}
    @{" CreatePalette     " LINK CreatePalette}
    @{" DisplayPalette    " LINK DisplayPalette}
    @{" FreePalette       " LINK FreePalette}
    @{" Fade              " LINK Fade}
    @{" FadeOut           " LINK FadeOut}
    @{" GetPicturePalette " LINK GetPicturePalette}
    @{" GetScreenPalette  " LINK GetScreenPalette}
    @{" Green             " LINK Green}
    @{" InitPalette       " LINK InitPalette}
    @{" NbColour          " LINK NbColour}
    @{" PalRrgb           " LINK PalRgb}
    @{" Red               " LINK Red}
    @{" Rgb               " LINK Rgb}
    @{" UsePalette        " LINK UsePalette}

  @{b}Example:@{ub}

    @{" Fading workbench  " LINK "/Examples/Sources/Palette.pb/Main"}

@ENDNODE


@NODE ASyncFade

    @{b}SYNTAX@{ub}
  ASyncFade(#Palette1, #Palette2, Step, NbLoop, ScreenID)

    @{b}STATEMENT@{ub}
  Same as NFade() routine, but doesn't halt the program. The fade
  is executed in the background.

  You can use NAsyncStatus() to find out if the background fade is
  finished or not.

@ENDNODE


@NODE ASyncFadeStatus

    @{b}SYNTAX@{ub}
  Result.b = ASyncFadeStatus

    @{b}STATEMENT@{ub}
  Return '-1' if the Fade is still running or '0' if
  the fade has finished.

  Example:

  Repeat                  ; Typical loop to wait for the end
    NVWait                ; of the background fade.
  Until NASyncStatus = 0  ;

@ENDNODE


@NODE Fade

    @{b}SYNTAX@{ub}
  Fade(#Palette1, #Palette2, Step, NbLoop, ScreenID)

    @{b}STATEMENT@{ub}
  Do a nice fade between the two palettes. The palettes must have the
  same number of colours or it could crash. Step controls the speed
  of the Fade (1 is the fastest, >1 numbers will slow down the fade
  speed). NbLoop controls how many loops the Fade must do before
  exiting. By default the Fade ALWAYS executes 255 loops. So you can
  adjust it manually (ie: with a Step of 2, you should use an NbLoop
  of 255/2 +-= 127)

  This function is optimized for speed, and gives very good results
  on any Amigas (020 recommended though), with high-coloured
  screens (upto 256 colours).

@ENDNODE


@NODE FreePalette

    @{b}SYNTAX@{ub}
  FreePalette(#Palette)

    @{b}STATEMENT@{ub}
  Free the memory allocated to the given #Palette.

@ENDNODE


@NODE InitPalette

    @{b}SYNTAX@{ub}
  result.l = InitPalette(#NumPaletteMax)

    @{b}FUNCTION@{ub}
  Init all the Palette  environments for later use.  You  must  put  this
  function at the top of your source code if you want to use the Palette
  commands.

  #NumPaletteMax : Maximum number of Palettes to handle.

@ENDNODE


@NODE Red

    @{b}SYNTAX@{ub}
  Red.w = Red(ColourIndex)

    @{b}FUNCTION@{ub}
  Return the Red value of the colour found in the current palette.
  Returned value is always between 0 and 255.

@ENDNODE


@NODE Green

    @{b}SYNTAX@{ub}
  Green.w = Green(ColourIndex)

    @{b}FUNCTION@{ub}
  Return the Green value of the colour found in the current palette.
  Returned value is always between 0 and 255.

@ENDNODE


@NODE Blue

    @{b}SYNTAX@{ub}
  Blue.w = Blue(ColourIndex)

    @{b}FUNCTION@{ub}
  Return the Blue value of the colour found in the current palette.
  Returned value is always between 0 and 255.

@ENDNODE


@NODE CreatePalette

    @{b}SYNTAX@{ub}
  res.l = CreatePalette(#Palette, NbColour)

    @{b}COMMAND@{ub}
  Tries to create a new palette with given argument. The size, in memory,
  taken by a palette object can be calculated like this:
    Size (in bytes) = NbColours * 12 + 12

  The created palette is ready to use and filled with colour 0.

@ENDNODE


@NODE Rgb

    @{b}SYNTAX@{ub}
  Rgb(ScreenID, ColourIndex, R, G, B)

    @{b}STATEMENT@{ub}
  Change directly the RGB value of a colour in the given Screen.

@ENDNODE


@NODE NbColour

    @{b}SYNTAX@{ub}
  Result.l = NbColour

    @{b}STATEMENT@{ub}
  Returns the number of colour of currently used palette.

@ENDNODE


@NODE PalRgb

    @{b}SYNTAX@{ub}
  PalRgb(ColourIndex, R, G, B)

    @{b}STATEMENT@{ub}
  Change the RGB value of a colour in the current palette.

@ENDNODE


@NODE GetScreenPalette

    @{b}SYNTAX@{ub}
  res.l = GetScreenPalette(#Palette, ScreenID)

    @{b}COMMAND@{ub}
  Tries to create a new palette and fill it with screen colour information.
  If res = 0 the palette could not be created.

@ENDNODE


@NODE GetPicturePalette

    @{b}SYNTAX@{ub}
  res.l = GetPicturePalette(#Palette, PictureID)

    @{b}COMMAND@{ub}
  Tries to create a new palette and fill it with picture colour information.
  If res = 0 the palette could not be created.

  PictureID is a pointer to an IFF/ILBM file in memory.

@ENDNODE


@NODE DisplayPalette

    @{b}SYNTAX@{ub}
  DisplayPalette(#Palette, ScreenID)

    @{b}STATEMENT@{ub}
  Display the given #Palette on the screen.

@ENDNODE


@NODE UsePalette

    @{b}SYNTAX@{ub}
  UsePalette(#Palette)

    @{b}STATEMENT@{ub}
  Change the current Palette to the given #Palette.

@ENDNODE


@NODE FadeOut

    @{b}SYNTAX@{ub}
  FadeOut(#Palette, Step, NbLoop, ScreenID)

    @{b}STATEMENT@{ub}
  It will display a very nice fade out from the given palette.
  The palette WILL be modified (at the end of the fading, the
  palette will be completely black). The fadeout speed can be
  controlled with the 'Step' parameter.

    If Step = 1 then the fading will be smooth and take 1 vwait
    before fading the next frame
    If Step = 2 fading will be 2 times faster than Step 1 ...

  NbLoop is used to fade partially a screen:

    If NbLoop = 255, the whole screen will be black at end, because
    with 255 loops, the fadeout is complete

    If NbLoop = 50, after 50 loop the FadeOut will stop. Test it
    to understand better :)

  This routine is optimized for speed and gives excellent results
  even on small Amiga. And more, it's fully system-friendly (no
  hardware bang...) so works on GFX card too ! It's better to use
  this routine than the Fade() to do standard Fade Out..

@ENDNODE