Read annotation text

=> | R0 = | 1
| R1 = | filename (or 0 for currently open)
| R2 = | pointer to word-aligned block to return data
| R3 = | size of block
| R4 = | what data to fetch

<= | R3 = | amount of data written

Currently only annotation can be read from the Wave format although PlayIt supports other formats which could conceivably contain text information (which may be made available in future versions). This should be rectified when PlayIt is internally redesigned in such a way to make this easier.

On entry bits set in R4 indicate which annotation items to try and extract:

bit | what to fetch | bit | what to fetch
0 | Sample name | 5 | Original medium
1 | Artist | 6 | Genre
2 | Comment | 7 | Creation software
3 | Copyright | 8 | Source supplier
4 | Creation date | 9-31 | (reserved)

The first part of the buffer is filled in with 32-bit pointers to the characters (ie char *txt[] in C). There is one pointer for each bit set in R4 so, for example, if R4 was &03 there would be two pointers occupying 8 bytes. The order of the pointers is in the same order as the bit list above. Pointers will be zero if the text was not available (or there was no room for it) otherwise they point to somewhere in the remainder of the buffer.

eg, suppose R4 was &2A (medium, copyright and artist) the buffer might look like this:

R2+0 | Pointer to Artist (R2+21)
R2+4 | Pointer to Copyright (R2+12)
R2+8 | Pointer to Medium (NULL)
R2+12 | "(c) 1999"
R2+21 | "Joe Bloggs"

and R3=31. Note that the strings can appear in any order (actually they appear in the order they are in the file) hence the pointers to help locate them.

You must ensure the buffer is at least big enough to hold the array of pointers since this is not checked (ie 4 times the number of bits set in R4). A partial string might be returned if the buffer gets filled (the terminator is still written in the last byte). The pointer will be zero if there was no room to even start the string.

In C, example extraction code might look like this:

`
char **st,i;
for (i=0,st=(char **)R2; i<32; i++)
if (R4 & (1<<i)) {
if (*st) printf("%s\n",*st);
st++;
}`

[ Parent ] [ Manual root ]