5. Stream access example

5.1 Basic program

(1) Reading the stream

Read streams A, B, and C into a_buf, b_buf, and c_buf.
(A_BUFSIZE, B_BUFSIZE, C_BUFSIZE are buffer sizes in sectors)

Uint8 work[STM_WORK_SIZE(STMGRP_OPEN_MAX, STM_OPEN_MAX)]; /* Work area */
Sint32 a_id, b_id, c_id; /* File identifier */
StmGrpHn abc_grp; /* Stream group handle */
StmHn a_stm, b_stm, c_stm; /* Stream handle */
StmKey key; /* Stream key */
Uint8 a_buf[A_BUFSIZE * STM_UNIT_FORM1]; /* Transfer area A */
Uint8 b_buf[B_BUFSIZE * STM_UNIT_FORM2]; /* Transfer area B */
Uint8 c_buf[C_BUFSIZE * STM_UNIT_FORM1]; /* Transfer area C */

GFS_Init(･･･); /* Initialize the file system */
STM_Init(STMGRP_OPEN_MAX, STM_OPEN_MAX, work); /* Initialize the stream system */
a_id = GFS_NameToId(･･･); /* Get file identifier */
・
・
・
abc_grp = STM_OpenGrp(); /* Open stream group */
                                                             /* Stream key settings */
STM_KEY_CN(&key) = STM_KEY_NONE; /* Channel number */
STM_KEY_CIMSK(&key) = STM_KEY_CIVAL(&key) = STM_KEY_NONE; /* Coding information */
/* Open stream by file identifier */
STM_KEY_SMMSK(&key) = STM_KEY_SMVAL(&key) = STM_SM_VIDEO; /* Video stream */
a_stm = STM_OpenFid(abc_grp, a_id, &key, STM_LOOP_NOREAD); /* Stream A */
STM_KEY_SMMSK(&key) = STM_KEY_SMVAL(&key) = STM_SM_AUDIO; /* Audio stream */
b_stm = STM_OpenFid(abc_grp, b_id, &key, STM_LOOP_NOREAD); /* Stream B */
STM_KEY_SMMSK(&key) = STM_KEY_SMVAL(&key) = STM_SM_DATA; /* Data stream */
c_stm = STM_OpenFid(abc_grp, c_id, &key, STM_LOOP_NOREAD); /* Stream C */

/* Transfer area settings */
STM_SetTrBuf(a_stm, a_buf, A_BUFSIZE, STM_UNIT_FORM1);
STM_SetTrBuf(b_stm, b_buf, B_BUFSIZE, STM_UNIT_FORM2);
STM_SetTrBuf(c_stm, c_buf, C_BUFSIZE, STM_UNIT_FORM1);

/* Stream access */
STM_SetExecGrp(abc_grp); /* Set execution group */
while (1) {
    if (STM_ExecServer() == STM_EXEC_COMPLETED) {
        break; /* Stream access ends */
    }
    user(); /* User processing */
}
STM_CloseGrp(abc_grp); /* Close stream group */

(2) Transfer area settings

When setting the transfer area, the following two processing methods are different.

(a) STM_SetTrBuf(stm, buffer, A_BUFSIZE, STM_UNIT_FORM1)

(b) STM_SetTrBuf(stm, buffer, A_BUFSIZE * STM_UNIT_FORM1, STM_UNIT_WORD)

(a) When the transfer area size is in sectors

Since the number of sectors that can be retrieved from a partition within a CD block is known in advance, it can be processed as follows.

Figure 5.1 Transfer processing in sector units

(b) When the size of the transfer area is not in sectors

Since the number of sectors that can be retrieved from the partition in the CD block is unknown, proceed as follows.

Figure 5.2 Transfer processing when not in sector units

The next stream cannot be transferred while the dotted line loop is repeated. Therefore, when accessing two or more streams at the same time, you should use method (a) to transfer them, except in special cases.
If Form1 and Form2 sectors are mixed in one stream, method (b) is the only way to transfer them.

(3) Transfer function settings

In program (1), if you want to transfer the data of stream B to read_buf while decompressing it using the function "decodeFunc", make the following changes.

(a) Change STM_SetTrBuf in the dotted line to STM_SetTrFunc.

STM_SetTrFunc(b_stm, decodeFunc, read_buf);

This will cause decodeFunc to start every time the server function STM_ExecServer attempts to transfer stream B data.

(b) “decodeFunc” will be as follows.

Uint8 read_buf[READBUF_SIZE];

Sint32 decodeFunc(void *obj, StmHn stm, Sint32 nsct)
{
	Sint32 i;
	Sint32 read_len; /* Number of longwords transferred by subFunc */
	Sint32 nlongword; /* Number of longwords to be transferred */
	Uint32 *src; /* Source address */
	Sint32 dadr; /* Address/variation per longword transfer */
	Uint32 *buffer; /* Transfer area */

	/* Conversion from number of sectors to number of words (call before starting transfer) */
	nlongword = STM_SctToWord(stm, nsct) / 2;

	src = STM_StartTrans(stm, &dadr); /* Start transfer */
	buffer = (Uint8 *)obj; /* The third argument of STM_SetTrFunc is passed to obj */

	for (i = 0; i< nlongword; i += read_len) {

		/* Function that returns the number of expanded bytes */
		buffer += subFunc(src, dadr, buffer, &read_len);
		src += read_len * dadr;
	}
	return (nsct); /* Return the number of transferred sectors */
}

(c) Must be transferred sector by sector.

(d) If the data has not been transferred when decodeFunc finishes, (-1) must be returned.
In this case, other streams cannot be transferred until the data has been transferred. After transferring data, return the number of transferred sectors. STM_StartTrans must not be called during this time.

Figure 5.3 Operation when using transfer function

(4) Closing the stream in which the transfer function is registered

If you close the stream immediately after the transfer function returns (-1), the stream system will keep calling the transfer function until the transfer function returns a value greater than or equal to 0. Please return a value greater than or equal to 0 when the transfer is complete.

5.2 Use with file systems

If you want to read from a CD using the file system while using the stream system, you must pause the drive. There are two ways to do this:

(a) Execute STM_SetExecGrp(NULL). (Completion return)

(b) Execute STM_NwSetExecGrp(NULL) and set the function value of STM_ExecServer to
Call server functions until STM_EXEC_TSKEND. (Immediate return) After the file system has finished reading, resume reading the stream using STM_SetExecGrp(grp).

＜ example＞ Transfer read-ahead stream data while reading in the file system

         ・
         ・ /* Read ahead the stream */
STM_SetExecGrp(NULL); /* Pause the drive */
GFS_NwFread(………);
while (1) {
	if (GFS_NwExecOne(gfs) == GFS_SVR_COMPLETED) /* Read file */
		break;
	STM_ExecTrans(stm); /* Transfer stream data */
}
STM_SetExecGrp(grp); /* Resume reading stream */