@DATABASE Sound V1.00
$VER: PureBasic - Sound library V1.00 (05.10.1999) © Fantaisie Software
@NODE MAIN "Sound V1.00"

  @{b}PureBasic - Sound V1.00@{ub}

    Cette bibliothèque est destinée à gérer les sons sous le
    PureBasic. Et croyez-nous, on a passé un temps fou à optimiser
    toutes les fonctions disponibles. Il en résulte une gestion
    des sons qui respecte le système, ultra rapide et qui utilise
    les 4 canaux audios de l'Amiga. Le format des sons utilisé
    est l'IFF/8SVX.

  @{b}Commands summary:@{ub}

    @{" ChangeSoundPeriod " LINK ChangeSoundPeriod }
    @{" ChangeSoundVolume " LINK ChangeSoundVolume}
    @{" CreateSound       " LINK CreateSound}
    @{" DecodeSound       " LINK DecodeSound}
    @{" FreeSound         " LINK FreeSound}
    @{" GetSoundLength    " LINK GetSoundLength}
    @{" InitSound         " LINK InitSound}
    @{" LoadSound         " LINK LoadSound}
    @{" PeekSoundData     " LINK PeekSoundData}
    @{" PlaySound         " LINK PlaySound}
    @{" PokeSoundData     " LINK PokeSoundData}
    @{" SaveSound         " LINK SaveSound}
    @{" SetSoundChannels  " LINK SetSoundChannels}
    @{" SetSoundPeriod    " LINK SetSoundPeriod}
    @{" SetSoundVolume    " LINK SetSoundVolume}
    @{" SoundFilter       " LINK SoundFilter}
    @{" StopSound         " LINK StopSound}
    @{" UseSoundChannels  " LINK UseSoundChannels}

    @{" Sound Demo " LINK PureBasic:Examples/Sources/Sound.pb/Main}
@ENDNODE


@Node ChangeSoundPeriod

    @{b}Syntaxe@{ub}
  Résultat.w = ChangeSoundPeriod(@{b}#Sound@{ub}.w,@{b}Period@{ub}.w)

    @{b}Résumé@{ub}
  Change en temps réel la période du son spécifié (qui doit être
  en train d'être joué). Cette fonction renvoie le masque des
  canaux audios affectés par ce changement de période.

  La période originale du son (définie par @{" SetSoundPeriod() " LINK SetSoundPeriod})
  n'est pas affectée par cette fonction.


  @{b}#Sound@{ub}: Identifiant numérique du son

  @{b}Period@{ub}: Nouvelle période du son

@EndNode


@Node ChangeSoundVolume

    @{b}Syntaxe@{ub}
  Résultat.w = ChangeSoundVolume(@{b}#Sound@{ub}.w,@{b}Volume@{ub}.w)

    @{b}Résumé@{ub}
  Change en temps réel le volume du son spécifié (qui doit être
  en train d'être joué). Cette fonction renvoie le masque des
  canaux audios affectés par ce changement de période.

  Le volume original du son (défini par @{" SetSoundVolume() " LINK SetSoundVolume})
  n'est pas affecté par cette fonction.

  @{b}#Sound@{ub}: Identifiant numérique du son

  @{b}Volume@{ub}: Nouvelle valeur du volume

@EndNode


@Node CreateSound

    @{b}Syntaxe@{ub}
  Résultat.l = CreateSound(@{b}#Sound@{ub}.w,@{b}Length@{ub}.l)

    @{b}Résumé@{ub}
  Crée un nouveau son entièrement vide. La période, le volume et
  les canaux sont initialisés à 0. Pour écrire dans la partie
  'Data' du son et ainsi pouvoir créer réellement le son, vous
  pouvez utiliser la commande @{" PokeSoundData() " LINK PokeSoundData}. Si le résultat
  de cette fonction est NULL, alors le son n'a pas pu être créé.


  @{b}#Sound@{ub}: Identifiant numérique de l'objet à créer.

  @{b}Length@{ub}: Longueur du son (longueur des 'Data')

@EndNode


@Node DecodeSound

    @{b}Syntaxe@{ub}
  Résultat.w = DecodeSound(@{b}#Sound@{ub}.w,@{b}Pointer@{ub}.l)

    @{b}Résumé@{ub}
  Initialise un son à partir d'un fichier IFF/8SVX inclu
  dans le programme via la commande 'IncludeBinary'.
  Si le Résultat est NULL, alors le son n'a pas pu être
  initialisé correctement.

  * Le volume de ce son est mis à 64.
  * Les canaux sont mis à 15.


  @{b}#Sound@{ub}: Identifiant numerique du son

  @{b}Pointer@{ub}: Pointeur vers le son IFF (principalement '?label').

@EndNode


@Node FreeSound

    @{b}Syntaxe@{ub}
  FreeSound(@{b}#Sound@{ub}.w)

    @{b}Résumé@{ub}
  Libère un son de la mémoire et détruit toutes les informations
  le concernant.


  @{b}#Sound@{ub}: Indentifiant numérique du son
@EndNode


@Node GetSoundLength

    @{b}Syntaxe@{ub}
  @{b}Résultat@{ub}.l = GetSoundLength(@{b}#Sound@{ub}.w)

    @{b}Résumé@{ub}
  Retourne la longueur du son spécifié. Utile pour éviter
  d'écrire en dehors de la zone de 'Data' lorsqu'on
  utilise la commande @{" PokeSoundData() " LINK PokeSoundData}.


  @{b}#Sound@{ub}: Identifiant numérique du son.
@EndNode


@Node InitSound

    @{b}Syntaxe@{ub}
  @{b}Résultat@{ub}.w = InitSound(@{b}Objects@{ub}.l)

    @{b}Résumé@{ub}
  Initialise l'environnement nécessaire à la gestion des sons.
  Vous devez appeler cette fonction avant d'appeler une autre
  fonction de cette bibliothèque. Si le 'Résultat' est NULL,
  alors il n'y a plus assez de mémoire libre.


  @{b}Objects@{ub}: Nombre maximal de sons à gérer.

@EndNode


@Node LoadSound

    @{b}Syntaxe@{ub}
  @{b}Résultat@{ub}.b = LoadSound(@{b}#Sound@{ub}.w,@{b}FileName@{ub}$)

    @{b}Résumé@{ub}
  Charge le son IFF/8SVX spécifié en mémoire. Le son est
  prêt à être joué. Si le résultat est NULL, alors le son
  n'a pas pu être chargé.


  * Le volume du son est mis à 64.
  * Les canaux audios sont initialisés à 15.


  @{b}#Sound@{ub}: Identifiant numérique su nouveau son.

  @{b}FileName@{ub}: Chemin et nom du fichier son IFF/8SVX

@EndNode


@Node PeekSoundData

    @{b}Syntaxe@{ub}
  @{b}Résultat@{ub}.b = PeekSoundData(@{b}#Sound@{ub}.w,@{b}Position@{ub}.l)

    @{b}Résumé@{ub}
  Retourne la valeur du 'Data' du son spécifié à une position donnée.
  Cette valeur est comprise entre -128 et +127


  @{b}#Sound@{ub}: Identifiant numérique du son.

  @{b}Position@{ub}: Position à l'intérieur du 'SoundData'
@EndNode


@Node PlaySound

    @{b}Syntaxe@{ub}
  @{b}Résultat@{ub}.w = PlaySound(@{b}#Sound@{ub}.w,@{b}Repeat@{ub}.w)

    @{b}Résumé@{ub}
  Joue le son spécifé en tenant compte de sa période, de son
  volume et de ses canaux. Cette fonction renvoie le masque des
  canaux audios affectés par ce changement de période. Si
  la valeur retournée est NULL alors le son ne peut pas
  être joué.


  @{b}#Sound@{ub}: Identifiant numérique du son à jouer.

  @{b}Repeat@{ub}: Nombre de répétions pour ce son. Si vous voulez
          qu'il soit répété à l'infini, utiliser une valeur
          négative.
@EndNode


@Node PokeSoundData

    @{b}Syntaxe@{ub}
  PokeSoundData(@{b}#Sound@{ub}.w,@{b}Position@{ub}.l,@{b}Data@{ub}.b)

    @{b}Résumé@{ub}
  Ecrit une valeur dans le 'SoundData' à la position donnée


  @{b}#Sound@{ub}: Identifiant numérique du son

  @{b}Position@{ub}: Position à laquelle la valeur doit être écrite.

  @{b}Data@{ub}: Valeur à écrire (comprise entre -128 et +127).
@EndNode


@Node SaveSound

    @{b}Syntaxe@{ub}
  @{b}Résultat@{ub}.b = SaveSound(@{b}#Sound@{ub}.w,@{b}FileName@{ub}$)

    @{b}Résumé@{ub}
  Sauvegarde le son spécifié à l'endroit spécifié par 'Filename'. Si
  le 'Résultat' est NULL, alors le son n'a pas pu être sauvegardé
  à cet endroit.


  @{b}#Sound@{ub}: Identifiant numérique du son à sauvegarder.

  @{b}FileName@{ub}: Chemin et nom du fichier où le son sera sauvegardé.

@EndNode


@Node SetSoundChannels

    @{b}Syntaxe@{ub}
  SetSoundChannels(@{b}#Sound@{ub}.w,@{b}Channels@{ub}.w)

    @{b}Résumé@{ub}
  Change l'affection des canaux pour le son spécifié. Chaque
  son a son propre paramétrage des canaux sur lesquels il sera
  joué (par la commande @{" PlaySound() " LINK PlaySound}).


  @{b}#Sound@{ub}: Identifiant numérique du son

  @{b}Channels@{ub}: Masque representant un canal ou une combinaison
            de canaux:

  Valeur du masque:

  1 = seulement le canal 0
  2 = seulement le canal 1
  4 = seulement le canal 2
  8 = seulement le canal 3

  Exemples de combinaisons:

   5 = canal 0 (valeur 1) et canal 2 (valeur 4)
  15 = tous les canaux (1+2+4+8)
@EndNode


@Node SetSoundPeriod

    @{b}Syntaxe@{ub}
  SetSoundPeriod(@{b}#Sound@{ub}.w,@{b}Period@{ub}.w)

    @{b}Résumé@{ub}
  Change la période interne du son qui sera utilisée
  par la commande @{" PlaySound() " LINK PlaySound}.


  @{b}#Sound@{ub}: Identifiant numérique du son.

  @{b}Period@{ub}: Nouvelle période du son.
@EndNode


@Node SetSoundVolume

    @{b}Syntaxe@{ub}
  SetSoundVolume(@{b}#Sound@{ub}.w,@{b}Volume@{ub}.w)

    @{b}Résumé@{ub}
  Change le volume interne du son spécifié qui sera utilisé
  par la commande @{" PlaySound() " LINK PlaySound}.


  @{b}#Sound@{ub}: Identifiant numérique du son.

  @{b}Volume@{ub}: Nouveau volume.
@EndNode


@Node SoundFilter

    @{b}Syntaxe@{ub}
  SoundFilter(@{b}State@{ub})

    @{b}Résumé@{ub}
  Active ou desactive le filtre passe-bas interne de l'Amiga
  (coupe les hautes fréquences).


  @{b}State@{ub}: 1 = Filtre activé, 0 = Filtre désactivé.
@EndNode


@Node StopSound

    @{b}Syntaxe@{ub}
  StopSound(@{b}#Sound@{ub}.w)

    @{b}Résumé@{ub}
  Arrête le son spécifié en train d'être joué.


  @{b}#Sound@{ub}: Identifiant numérique du son à stopper.
@EndNode


@Node UseSoundChannels

    @{b}Syntaxe@{ub}
  @{b}Résultat@{ub}.w = UseSoundChannels(@{b}Channels@{ub}.w)

    @{b}Résumé@{ub}
  Alloue ou libère les canaux sonores voulus. Si vous avez alloué
  tous les canaux (Channel = 15) et que vous voulez en libérer
  2, par exemple les canaux 2 et 3 vous pouvez appeler cette
  fonction avec 'Channels = 3' (canaux 1 et 2). Ainsi les canaux
  0 et 1 restent alloués tandis que les canaux 2 et 3 sont
  libérés. Si le 'Résultat' est FALSE, alors les canaux n'ont
  pas pus être alloués correctement.


  @{b}Channels@{ub}: Masque représentant les canaux à allouer.
@EndNode