7.Function specification

7.1 Scenario processing

one View table

Title function specification

Function Initializing branch playback

Function name BPL_Init

No 1.1

Format

Sint32 BPL_Init(Sint32 bstmmax, Sint32 brmax, Sint32 Keymax, void *work)

input

 bstmmax: Total number of branch streams to register brmax: Total number of branches keymax: Total number of stream key types work: Work area

output

none

function value

Error code

function

Initializes the workspace to use the branch playback library. All information about the set scenario will be cleared.
Be sure to run this before using the branch playback library.

remarks

1. The size of the work area is determined by BPL_WORK_SIZE(bstmmax,brmax,keymax) bytes.
   Place the work area on a 4-byte boundary.
   "example"
   Uint32 work[BPL_WORK_SIZE(bstmmax,brmax,keymax)/sizeof(Uint32)];

2. When setting different types of stream keys for different branch streams, the sum of those types becomes the keymax value.
   "example"
   When setting key1 (3 types of keys) to bstm1 and key2 (4 types of keys) to bstm2,
   keymax is the sum of key1 and key2, which is 7.
   If you set the same key1 to bstm1 and bstm2, keymax will be 3 for key1 only.

3. The BPL_Init function does not close the stream group being used.
   To force initialization while using the branch playback library, execute the BPL_Reset function.

one View table

Title function specification

Function Reset branch playback

Function name BPL_Reset

No 1.2

Format

Sint32 BPL_Reset(void)

input

none

output

none

function value

Error code

function

Aborts branch stream access and resets branch playback.
(Closes the stream group used by the branch playback library and initializes all information.)

one View table

Title function specification

Function Setting branch stream information

Function name BPL_SetStmInfo

No 1.3

Format

Sint32 BPL_SetStmInfo(Sint32 bstmid, Sint32 fid, Sint32 nkey, StmKey *keytbl)

input

 bstmid: Branch stream identifier (0≦bstmid＜ bstmmax) fid: File identifier nkey: Number of stream keys (nkey≦BPL_STMKEY_MAX) keytbl: Stream key table

output

none

function value

Error code

function

Set branch stream information (information about each stream that is actually read) for the branch stream.

remarks

1. By setting multiple stream keys in one file, you can read channel interleaved data.

2. The maximum stream key that can be set for one branch stream is BPL_STMKEY_MAX. The total number of stream key types that can be used in all streams is specified with the BPL_Enit function.

one View table

Title function specification

Function Get branch stream information

Function name BPL_GetStmInfo

No 1.4

Format

Sint32 BPL_GetStmInfo(Sint32 bstmid, Sint32 *fid, Sint32 *nkey, Stmkey *keytbl)

input

bstmid: branch stream identifier

output

 fid: File identifier nkey: Number of stream keys (nkey≦BPL_STMKEY_MAX) keytbl: Stream key table

function value

Number of branch destinations set (if negative, error code)

function

Gets the branch stream information set for the branch stream.
For the number of branch destinations, see the branch destination information setting function ( BPL_SetBranchInfo ).

one View table

Title function specification

Function Setting branch destination information

Function name BPL_SetBranchInfo

No 1.5

Format

Sint32 BPL_SetBranchInfo(Sint32 bstmid, Sint32 nbranch, Sint32 *brtbl)

input

 bstmid: Branch stream identifier nbranch: Number of branch destinations brtbl: Branch table

output

none

function value

Error code

function

Set branch destination information (branch destination candidates) for the branch stream.

remarks

1. Set the branch stream identifier of the branch candidate in the branch table.
   To set no branch destination, specify BPL_BR_NONE in the branch table element.

    brtbl[0] = BSTMID_A; brtbl[1] = BPL_BR_NONE; /* No branch destination (end of branch playback) */ brtbl[2] = BSTMID_B; nbranch = 3;

   The branch destination is specified using the BPL_SelectBranch function and branch number (position in the branch table).
   In this example, the branch process is as follows depending on the branch destination you select.

   Selected branch destination	Branch processing (when the branch execution switch of the server function is ON)
   Branch number 0	Branch to branch stream identifier BSTMID_A.
   Branch number 1	Branch playback ends. Immediately after selection, there will be no branch destination.
   Branch number 2	Branch to branch stream identifier BSTMID_B.
   others	BPL_SelectBranch returns BPL_ERR_BRNO error and selection becomes invalid.

2. The number of streams must meet the following conditions:

 X + Y ≦ Z
 X: Number of stream keys set in bstmid Y: Total number of branch destination stream keys Z: Maximum number of streams that can be opened at the same time (specified with the STM_Init function)

one View table

Title function specification

Function Get branch destination information

Function name BPL_GetBranchInfo

No 1.6

Format

Sint32 BPL_GetBranchInfo(Sint32 bstmid, Sint32 *nbrabch, Sint32 *brtbl, Sint32 nelem)

input

 bstmid: Branch stream identifier nelem: Number of elements in branch table

output

 nbranch: Number of branch destinations (0 if there are no branch candidates) brtbl: Branch table (up to nelem branch candidates are stored from the beginning)

function value

Error code

function

Get the branch destination information set in the branch stream.

7.2 Branch playback processing

one View table

Title function specification

Function Specifying the playback start stream

Function name BPL_SetStart

No 2.1

Format

Sint32 BPL_SetStart(Sint32 bstmid)

input

bstmid: Branch stream identifier (BPL_BR_NONE: Stop branch playback)

output

none

function value

Error code

function

Specify the playback start stream (branch stream at the beginning of the scenario).
Specifying BPL_BR_NONE for the branch stream identifier will stop branch playback.

one View table

Title function specification

Function Running a branch playserver

Function name BPL_ExecServer

No 2.2

Format

Sint32 BPL_ExecServer(Bool chgsw)

input

chgsw: Branch execution switch (ON: perform branch processing, OFF: do not perform branch processing)

function value

Branch playback state

function

Run the branch playserver. When the branch execution switch is ON, branch processing (branch stream switching processing) is performed.

(1) Branch playback state

constant name	explanation
BPL_SVR_COMPLETED	Branch playback ends
BPL_SVR_WAITSEL	Waiting for branch destination selection
BPL_SVR_SELECT	Branch destination decision
BPL_SVR_NOBRN	No branch destination

For details on the branch playback state, see " 3.3 Branch playback state transition ".

one View table

Title function specification

Function Branch destination selection

Function name BPL_SelectBranch

No 2.3

Format

Sint32 BPL_SelectBranch(Sint32 brno)

input

brno: branch number

output

none

function value

Error code

function

Select the branch destination according to the specified branch number.

remarks

1. If you specify the branch execution switch ON when executing BPL_ExecServer, branch processing will actually be performed.
   (The selected branch destination switches to the current stream.)

2. Branch destination selection must be performed even if there is only one branch candidate.

one View table

Title function specification

Function Get current stream

Function name BPL_GetCurStm

No 2.4

Format

Sint32 BPL_GetCurStm(Sint32 nelem, Sint32 *stmtbl)

input

nelem: Number of elements in the stream handle table (nelem≦BPL_STMKEY_MAX)

output

stmtbl: stream handle table

function value

Branch stream identifier (if negative, there is no corresponding branch stream)

function

Gets the current stream (branch stream identifier and stream handle) that is being read/taken.

remarks

1. A stream handle corresponding to each stream key is set in the stream handle table.

one View table

Title function specification

Function Obtaining the branch destination stream

Function name BPL_GetNextStm

No 2.5

Format

Sint32 BPL_GetNextStm(Sint32 nelem, StmHn *stmtbl)

input

nelem: Number of elements in the stream handle table (nelem≦BPL_STMKEY_MAX)

output

stmbl: stream handle table

function value

Branch stream identifier (if negative, there is no corresponding branch stream)

function

Get the branch destination stream (branch stream identifier and stream handle).

remarks

1. A stream handle corresponding to each stream key is set in the stream handle table.

2. The function value is always negative until a branch target is selected (BPL_SelectBranch is executed).

one View table

Title function specification

Function Get stream group

Function name BPL_GetStmGrp

No 2.6

Format

StmGrpHn BPL_GetStmGrp(void)

input

none

output

none

function value

stream group handle

function

Gets the handle of the stream group used by the branch playback library.

remarks

1. The branch playback library opens one stream group during operation.
   At the end of branch playback, the stream group handle will be NULL.