@DATABASE Palette V1.10
$VER: Palette V1.10 (06.01.1998) by Laboureur -> AlphaSOUND <- Frédéric
@NODE MAIN "Palette V1.10"

    @{b}Palette V1.10 General Information:@{ub}

  * Blitz Basic II library number         : #139
  * Library size when linked to executable: 1192 bytes
  * Number of commands                    : 17
  * Ressources automatically freed at end : Yes

  NInitPalette() must be put before any other Palette functions
  or you will enjoy BIG crashs.

  NOTE: All the RGB value are between 0 and 255 colours to support
  AGA and GFX cards display, so ROM 3.0+ is needed. Note it will
  work on any Amiga with Rom 3.0+ (Amiga 500 - Old Chip Set too).

    @{b}Commands summary:@{ub}

  @{" NASyncFade         " LINK NASyncFade} Statement
  @{" NASyncFadeStatus   " LINK NASyncFadeStatus} Function (Byte)
  @{" NBlue              " LINK NBlue} Function (Word)
  @{" NCreatePalette     " LINK NCreatePalette} Command (Long)
  @{" NDisplayPalette    " LINK NDisplayPalette} Statement
  @{" NFreePalette       " LINK NFreePalette} Statement
  @{" NFade              " LINK NFade} Statement
  @{" NFadeOut           " LINK NFadeOut} Statement
  @{" NGetPicturePalette " LINK NGetPicturePalette} Function (Long)
  @{" NGetScreenPalette  " LINK NGetScreenPalette} Function (Long)
  @{" NGreen             " LINK NGreen} Function (Word)
  @{" NInitPalette       " LINK NInitPalette} Function (Boolean)
  @{" NNbColour          " LINK NNbColour} Function (Long)
  @{" NPalRrgb           " LINK NPalRgb} Statement
  @{" NRed               " LINK NRed} Function (Word)
  @{" NRgb               " LINK NRgb} Statement
  @{" NUsePalette        " LINK NUsePalette} Statement

@ENDNODE


@NODE NASyncFade

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

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

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

@ENDNODE


@NODE NASyncFadeStatus

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

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

  Example:

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

@ENDNODE


@NODE NFade

    @{b}SYNTAX@{ub}
  NFade(#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 allow to control
  the speed of the Fade (1 is the fastest, >1 numbers will slowdown
  the fade speed). NbLoop allow to tell how many loop the Fade must
  do before exit. By default the Fade execute ALWAYS 255 loop. So
  you can adjust it manually (ie: with a Step of 2, you should
  use a NbLoop of 255/2 +-= 127)

  This function is optimized for speed, and give very good result
  on any Amigas (020 recommended tough), with high coloured
  screens (8 depths..).

@ENDNODE


@NODE NFreePalette

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

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

@ENDNODE


@NODE NInitPalette

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

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

  #NumPaletteMax : Maximum number of Palette to handle.

@ENDNODE


@NODE NRed

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

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

@ENDNODE


@NODE NGreen

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

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

@ENDNODE


@NODE NBlue

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

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

@ENDNODE


@NODE NCreatePalette

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

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

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

@ENDNODE


@NODE NRgb

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

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

@ENDNODE


@NODE NNbColour

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

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

@ENDNODE


@NODE NPalRgb

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

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

@ENDNODE


@NODE NGetScreenPalette

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

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

@ENDNODE


@NODE NGetPicturePalette

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

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

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

@ENDNODE


@NODE NDisplayPalette

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

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

@ENDNODE


@NODE NUsePalette

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

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

@ENDNODE


@NODE NFadeOut

    @{b}SYNTAX@{ub}
  NFadeOut(#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 all black). The fadeout speed can be controled
  with the 'Step' parameter.

    If Step = 1 then the fading will be smooth and take 1 vwait
    before fadeout the next frame
    If Step = 2 fading will be 2 time 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 give 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 NFade() to do standard Fade Out..
@ENDNODE