Opcodes de tableaux

Opcodes de tableaux

Liste des opcodes de tableaux (6.12) :

Certaines instructions pour travailler avec des tableaux dans Csound (voir aussi le chapître array dans le Csound FLOSS Manual:)

Nom de variable

Un tableau doit être créé (via init ou fillarray) sous la forme kNomTableau suivi de crochets. Les crochets déterminent les dimensions du tableau. Ainsi,

kArr[] init 10

crée un tableau unidimensionnel (un vecteur) de longueur 10, tandis que

kArr[][] init 10, 10

crée un tableau à deux dimensions avec 10 lignes et 10 colonnes.

Après l'initialisation du tableau, on y fait référence comme un tout sans les crochets. Les crochets ne sont utilisés que pour indexer un élément :

kArr[]   init 10             ;with brackets because of initialization
kLen     = lenarray(kArr)    ;without brackets
kFirstEl = kArr[0]           ;indexing with brackets

On utilise la même syntaxe pour une simple copie via l'opérateur '=' :

kArr1[] fillarray 1, 2, 3, 4, 5
kArr2[] = kArr1              ;creates kArr2 as copy of kArr1

k-rate

Noter que la plupart des opérations sur les tableaux ne se font actuellement qu'au taux-k. Ainsi, comme pour tout autre opcode de taux-k, une opération sur les tableaux sera automatiquement répétée à chaque cycle-k. Par exemple, le code suivant réécrit le tableau avec différentes valeurs aléatoires à chaque cycle-k, tant que l'instrument est actif :

kArr[] init 10
kIndx  = 0
until kIndx == lenarray(kArr) do
  kArr[kIndx] rnd31 10, 0
  kIndx += 1
od

Pour éviter cela, on doit l'organiser de la manière habituelle, par exemple en utilisant un déclencheur :

kArr[] init 10
kTrig metro 1
if kTrig == 1 then ;do the following once a second
  kIndx  = 0
  until kIndx == lenarray(kArr) do
    kArr[kIndx] rnd31 10, 0
    kIndx += 1
  od
endif

Création/initialisation

La manière habituelle de créer un tableau est d'utiliser init :

kArr[]   init 10     ;creates one-dimensional array with length 10
kArr[][] init 10, 10 ;creates two-dimensional array

On peut aussi créer un tableau unidimensionnel et le remplir de valeurs distinctes au moyen de l'opcode fillarray. La ligne suivante crée un vecteur de longueur 4 et le remplit avec les nombres [1, 2, 3, 4]:

kArr[] fillarray 1, 2, 3, 4

Longueur

La fonction lenarray(kArr) retourne la longueur d'un tableau. Voir l'exemple pour la fonction lenarray.

Copie d'un tableau vers ou d'une table

copyf2array kArr, kfn

copie les données d'une table de fonction dans un vecteur.

copya2ftab kArr, kfn

copie les données d'un vecteur dans une table de fonction.

Voir les exemples pour les opcodes copyf2array and copya2ftab.

Opérations sur les tableaux : maths

+, -, *, / avec un nombre

Si les quatre opérateurs de base sont utilisés entre un tableau et un nombre scalaire, l'opération est appliquée à chaque élément. La manière la plus sûre de le faire est de stocker le résultat dans un nouveau tableau :

kArr1[] fillarray 1, 2, 3
kArr2[] = kArr1 + 10    ;(kArr2 is now [11, 12, 13])

Voici un exemple des opérations tableau/scalaire. Il utilise le fichier array_scalar_math.csd.

Exemple 3. Exemple des opérations tableau/scalaire

<CsoundSynthesizer>
<CsOptions>
-n -m128
</CsOptions>
<CsInstruments>


  instr 1

;create array and fill with numbers 1..10
kArr1[] fillarray 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

;print content
        printf  "%s", 1, "\nInitial content:\n"
kndx    =       0
  until kndx == lenarray(kArr1) do
        printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr1[kndx]
kndx    +=      1
  od

;add 10
kArr2[] =       kArr1 + 10

;print content
        printf  "%s", 1, "\nAfter adding 10:\n"
kndx    =       0
  until kndx == lenarray(kArr2) do
        printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr2[kndx]
kndx    +=      1
  od

;subtract 5
kArr3[] =       kArr2 - 5

;print content
        printf  "%s", 1, "\nAfter subtracting 5:\n"
kndx    =       0
  until kndx == lenarray(kArr3) do
        printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr3[kndx]
kndx    +=      1
  od

;multiply by -1.5
kArr4[] =       kArr3 * -1.5

;print content
        printf  "%s", 1, "\nAfter multiplying by -1.5:\n"
kndx    =       0
  until kndx == lenarray(kArr4) do
        printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr4[kndx]
kndx    +=      1
  od

;divide by -3/2
kArr5[] =       kArr4 / -(3/2)

;print content
        printf  "%s", 1, "\nAfter dividing by -3/2:\n"
kndx    =       0
  until kndx == lenarray(kArr5) do
        printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr5[kndx]
kndx    +=      1
  od

;turnoff
        turnoff
  endin
  

</CsInstruments>
<CsScore>
i 1 0 .1
</CsScore>
</CsoundSynthesizer>


+, -, *, / avec un autre tableau

Si les quatre opérateurs de base sont utilisés entre deux tableaux, l'opération est appliquée élément à élément. Le résultat peut être stocké directement dans un nouveau tableau :

kArr1[] fillarray 1, 2, 3
kArr2[] fillarray 10, 20, 30
kArr3[] = kArr1 + kArr2    ;(kArr3 is now [11, 22, 33])

Voici un exemple des opérations de tableau. Il utilise le fichier array_array_math.csd.

Exemple 4. Exemple des opérations de tableau

<CsoundSynthesizer>
<CsOptions>
-n -m128
</CsOptions>
<CsInstruments>

  instr 1

;create array and fill with numbers 1..10 resp .1..1
kArr1[] fillarray 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
kArr2[] fillarray 1, 2, 3, 5, 8, 13, 21, 34, 55, 89

;print contents
        printf  "%s", 1, "\nkArr1:\n"
kndx    =       0
  until kndx == lenarray(kArr1) do
        printf  "kArr1[%d] = %f\n", kndx+1, kndx, kArr1[kndx]
kndx    +=      1
  od
        printf  "%s", 1, "\nkArr2:\n"
kndx    =       0
  until kndx == lenarray(kArr2) do
        printf  "kArr2[%d] = %f\n", kndx+1, kndx, kArr2[kndx]
kndx    +=      1
  od

;add arrays
kArr3[] =       kArr1 + kArr2

;print content
        printf  "%s", 1, "\nkArr1 + kArr2:\n"
kndx    =       0
  until kndx == lenarray(kArr3) do
        printf  "kArr3[%d] = %f\n", kndx+1, kndx, kArr3[kndx]
kndx    +=      1
  od

;subtract arrays
kArr4[] =       kArr1 - kArr2

;print content
        printf  "%s", 1, "\nkArr1 - kArr2:\n"
kndx    =       0
  until kndx == lenarray(kArr4) do
        printf  "kArr4[%d] = %f\n", kndx+1, kndx, kArr4[kndx]
kndx    +=      1
  od

;multiply arrays
kArr5[] =       kArr1 * kArr2

;print content
        printf  "%s", 1, "\nkArr1 * kArr2:\n"
kndx    =       0
  until kndx == lenarray(kArr5) do
        printf  "kArr5[%d] = %f\n", kndx+1, kndx, kArr5[kndx]
kndx += 1
  od

;divide arrays
kArr6[] =       kArr1 / kArr2

;print content
        printf  "%s", 1, "\nkArr1 / kArr2:\n"
kndx    =       0
  until kndx == lenarray(kArr6) do
        printf  "kArr5[%d] = %f\n", kndx+1, kndx, kArr6[kndx]
kndx += 1
  od

;turnoff
        turnoff
        
  endin
  
</CsInstruments>
<CsScore>
i 1 0 .1
</CsScore>
</CsoundSynthesizer>


Application d'une fonction à un tableau

kArrRes maparray kArrSrc, "fun"

applique la fonction de taux-k à un argument, définie dans la chaîne de caractères, à chaque élément du vecteur.

Les fonctions utilisables sont par exemple abs, ceil, exp, floor, frac, int, log, log10, round, sqrt. Voici un simple exemple :

kArrSrc[] fillarray 1, 2, 3, 4, 5
kArrRes[] init      5
kArrRes   maparray  kArrSrc, "sqrt"

Voir l'exemple pour l'opcode maparray.

Opérations sur les tableaux : min, max, sum, scale, slice

Minimum et maximum

  kMin [,kMinIndx] minarray kArr

retourne la plus petite valeur d'un tableau et facultativement son indice.

  kMax [,kMaxIndx] maxarray kArr

retourne la plus grande valeur d'un tableau et facultativement son indice. Voir les exemples pour les opcodes minarray and maxarray.

Somme

  kSum sumarray kArr

retourne la somme de toutes les valeurs dans kArr. Voir l'exemple pour l'opcode sumarray.

Pondération

  scalearray kArr, kMin, kMax

pondère toutes les valeurs dans kArr entre kMin et kMax.

  kArr[] fillarray  1, 3, 9, 5, 6
         scalearray kArr, 1, 3

change kArr en [1, 1.5, 3, 2, 2.25]. Voir l'exemple pour l'opcode scalearray.

Extrait

  slicearray kArr, iStart, iEnd

retourne un extrait de kArr compris entre l'indice iStart et l'indice iEnd (inclus).

Il faut créer le tableau de destination de l'extrait par avance :

  kArr[]  fillarray  1, 2, 3, 4, 5, 6, 7, 8, 9
  kArr1[] init       5
  kArr2[] init       4
  kArr1   slicearray kArr, 0, 4        ;[1, 2, 3, 4, 5]
  kArr2   slicearray kArr, 5, 8        ;[6, 7, 8, 9]

Voir l'exemple pour l'opcode slicearray.

Reformatage

utiliser reshapearray pour changer le format d'un tableau sans modifier sa capacité (changer 1D en 2D et vice-versa). Voir l'exemple de l'opcode reshapearray.

Tableaux dans un UDO

La dimension d'un tableau en entrée doit être déclarée en deux endroits :

  • comme k[] ou k[][] dans la liste des types en entrée
  • comme kNom[], kNom[][] etc dans la liste xin.

Par exemple :

opcode FirstEl, k, k[]
;returns the first element of vector kArr
kArr[] xin
       xout   kArr[0]
endop

Voici un exemple d'un tableau dans un UDO. Il utilise le fichier array_udo.csd.

Exemple 5. Exemple d'un tableau dans un UDO

<CsoundSynthesizer>
<CsOptions>
-nm128
</CsOptions>
<CsInstruments>

  opcode FirstEl, k, k[]
  ;returns the first element of vector kArr
kArr[] xin
xout kArr[0]
  endop

  instr 1 
kArr[] fillarray 6, 3, 9, 5, 1
kFirst FirstEl kArr
printf "kFirst = %d\n", 1, kFirst
turnoff
  endin

</CsInstruments>
<CsScore>
i 1 0 .1
</CsScore>
</CsoundSynthesizer>


A noter que si un opcode (par exemple inrg) modifie les arguments de la liste d'arguments sur sa droite, on ne doit pas utiliser un élément de tableau indicé dans cette liste. Contrairement au variables normales, les tableaux ne sont pas changés par les opcodes.

Crédits

Cette page du manuel a été écrite par Joachim Heintz.
Juillet 2013

Nouveau dans Csound 6.00