MOVIE TOOLS GUIDECinepak for SEGA Saturn
BackForward
Cinepak for SEGA Saturn


4.6 Function details

 List
 Title

Function specifications

 Data

Initialize

 Data Name

CPK_Init

 No

1.1

Form
Bool CPK_Init (void)
input
none
output
none
Function value
TRUE if it can be initialized normally
If it cannot be initialized normally FALSE
function
Immediately after starting the program, it will be initialized to use this library.
remarks
When using this library, be sure to call this function at the beginning of the program.

 List
 Title

Function specifications

 Data

End processing

 Data Name

CPK_Finish

 No

1.2

Form
void CPK_Finish (void)
input
none
output
none
Function value
none
function
If you do not want to play the movie after that, call this function.

 List
 Title

Function specifications

 Data

Creating a handle (memory)

 Data Name

CPK_CreateMemMovie

 No

2.1

Form
CpkHn CPK_CreateMemMovie (CpkCreatePara * para)
input
para: Creation parameter
output
none
Function value
Movie handle (NULL if not created)
function
Create a move handle to play the move file in memory.
remarks

 List
 Title

Function specifications

 Data

Erase handle (memory)

 Data Name

CPK_DestroyMemMovi

 No

2.2

Form
void CPK_DestroyMemMovie (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function
Erase the movie handle.
Once you erase a handle, that movie handle can no longer be used.

 List
 Title

Function specifications

 Data

Creating a handle (file system)

 Data Name

CPK_CreateGfsMovie

 No

2.3

Form
CpkHn CPK_CreateGfsMovie (CpkCreatePara * para, GfsHn gfs)
input
para: Creation parameter
gfs: file handle
output
none
Function value
Movie handle (NULL if not created)
function
Create a movie handle to play the movie file on the file system.
remarks

 List
 Title

Function specifications

 Data

Erase handle (file system)

 Data Name

CPK_DestroyGfsMovi

 No

2.4

Form
void CPK_DestroyGfsMovie (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function

 List
 Title

Function specifications

 Data

Creating a handle (stream system)

 Data Name

CPK_CreateStmMovie

 No

2.5

Form
CpkHn CPK_CreateStmMovie (CpkCreatePara * para, StmHn stm)
input
para: Creation parameter
stm: file handle
output
none
Function value
Movie handle (NULL if not created)
function
Create a movie handle to play the movie file on the stream system.
remarks

 List
 Title

Function specifications

 Data

Erase handle (stream system)

 Data Name

CPK_DestroyStmMovi

 No

2.6

Form
void CPK_DestroyStmMovie (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function

 List
 Title

Function specifications

 Data

Play task

 Data Name

CPK_Task

 No

2.7 2.7

Form
void CPK_Task (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function
It reads files from CDs and expands images.
If NULL is specified for cpk, the playback task will be executed for all the handles being played.
remarks
Call this function periodically during movie playback.
Make the calling interval longer than the number of playback frames. If the number of frames is less than the number of frames, it cannot be played smoothly.
After reading this function, be sure to check if the display timing is set by CPK_IsDispTime. If CPK_IsDispTime returns TRUE, the tie to display the image  Since it is ming, please change the frame if it has been expanded to sprite VRAM. If it was expanded to memory, transfer it to VRAM. Then be sure to call CPK_CompleteDisp.
Note that if the extraction destination address is specified in VRAM, it will be expanded before the display timing.

 List
 Title

Function specifications

 Data

Judgment of display timing

 Data Name

CPK_IsDispTime

 No

2.8

Form
Bool CPK_IsDispTime (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
When the expansion of the frame image of the movie is completed and it is time to display it, TRUE
FALSE when it is not yet time to display
function
When this function returns to TRUE, it is time to display the image of one frame, so if it has been expanded to sprite VRAM, the frame will be changed. If it was expanded to memory, transfer the expanded contents to VRAM. Be sure to call CPK_CompleteDisp after that.

 List
 Title

Function specifications

 Data

Notification of display completion

 Data Name

CPK_CompleteDisp

 No

2.9

Form
void CPK_CompleteDisp (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function
Notifies the library that the image display is finished.
remarks
Call this function when CPK_IsDispFrame becomes TRUE. If not called, the movie will not play.

 List
 Title

Function specifications

 Data

V blank IN processing function

 Data Name

CPK_VblIn

 No

2.10

Form
void CPK_VblIn (void)
input
none
output
none
Function value
none
function
Manages the playback time of the movie.
remarks
When using this library, be sure to call this function with a V blank IN interrupt.

 List
 Title

Function specifications

 Data

Start playing

 Data Name

CPK_Start

 No

3.1 3.1

Form
void CPK_Start (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function
The movie will start playing.
remarks
You can play a movie only once for the generated movie handle.
If you want to play the same movie over and over again, generate a movie handle each time.

 List
 Title

Function specifications

 Data

Stop playing

 Data Name

CPK_Stop

 No

3.2

Form
void CPK_Stop (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function
Stops playing the movie.

 List
 Title

Function specifications

 Data

Pause

 Data Name

CPK_Pause

 No

3.3

Form
void CPK_Pause (CpkHn cpk, CpkPauseCmd cmd)
input
cpk: movie handle
cmd: Pause control command
output
Returns a Bool type return value.
TRUE : Command accepted
FALSE : Command was not accepted

Returns FALSE if:

Function value
none
function
Pauses and cancels the playback of the movie.

 List
 Title

Function specifications

 Data

Registration of the next movie to play

 Data Name

CPK_EntryNext

 No

3.4 3.4

Form
void CPK_EntryNext (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function
Register the movie handle to be played next. If you register a movie with this function, it will automatically switch to the next movie when the currently playing movie ends.
If you specify NULL, the registration will be canceled.
Even when forced switching is performed with CPK_Change, the movie registered with this function will be played next.

 List
 Title

Function specifications

 Data

Forced switching of movie

 Data Name

CPK_Change

 No

3.5

Form
void CPK_Change (void)
input
none
output
none
Function value
none
function
The currently playing movie is interrupted and the movie registered with CPK_EntryNext starts playing.

 List
 Title

Function specifications

 Data

Get the switching status of the movie

 Data Name

CPK_CheckChange

 No

3.6

Form
CpkChangeStatus CPK_CheckChange (void)
input
none
output
none
Function value
Forced switchability check value
function
Returns the possibility of switching when forced switching with CPK_Change.

 List
 Title

Function specifications

 Data

Expansion of specified frame

 Data Name

CPK_DecodeFrame

 No

3.7

Form
void CPK_DecodeFrame (CpkHn cpk, Sint32 frame_no)
input
cpk: movie handle
frame_no: Number of the frame to expand
output
none
Function value
none
function
Expands the image of the specified frame.
remarks
This function can be used only for the movie loaded in the memory.
In the application program, read the movie file, create a movie handle with CPK_CreateMemMovie, and then call this function.
This function cannot be used with the movie handles created by CPK_CreateGfsMovie and CPK_CreateStmMovie.
Use a keyframe-only movie file with no sound.

 List
 Title

Function specifications

 Data

Expansion of specified frame
(Difference frame guarantee)

 Data Name

CPK_DecodeFrameSafety

 No

3.8

Form
void CPK_DecodeFrameSafety (CpkHn cpk, Sint32 sample_no)
input
cpk: handle
sample_no: sample number
output
none
Function value
none
function
Expands the image of the specified frame.
remarks
CPK_DecodeFrameSafety processes the difference frame retroactively to the keyframe and outputs the correct image. It is used when accessing a movie containing a difference frame at random.
caution
Load it in advance and use it for memory playback.
If no audio is included, the frame number is the sample number. If you include audio, make sure that the sample number you specify does not become an audio sample. Please refer to smpcpk7.c because there is a process to get the sample number from the frame number.

 List
 Title

Function specifications

 Data

Deployment destination address setting

 Data Name

CPK_SetDecodeAddr

 No

4.1

Form
void CPK_SetDecodeAddr (CpkHn cpk, void * dec_addr, Sint32 dec_line_size)
input
cpk: movie handle
dec_addr: Address of the image expansion destination
dec_line_size: Number of bytes per line in the image expansion destination buffer
output
none
Function value
none
function
Expanded image Specify the address to transfer the image.
If the image expansion destination address is NULL, image expansion is not performed. The default is NULL.
Call this function before playing the movie.

 List
 Title

Function specifications

 Data

Setting the number of display colors

 Data Name

CPK_SetColor

 No

4.2

Form
void CPK_SetColor (CpkHn cpk, CpkColorType color)
input
cpk: movie handle
color: Number of display colors
output
none
Function value
none
function
Specify the number of display colors for the image. The default is 16 million colors.
Call this function before playing the movie.

 List
 Title

Function specifications

 Data

Setting the maximum number of transfer sectors

 Data Name

CPK_SetLoadNum

 No

4.3

Form
void CPK_SetLoadNum (CpkHn cpk, Sint32 load_sct)
input
cpk: movie handle
load_sct: Maximum number of transfer sectors
output
none
Function value
none
function
Sets the maximum number of transfer sectors when transferring from the CD buffer to the library's internal buffer. The default is 20 sectors.
Call this function before playing the movie.

 List
 Title

Function specifications

 Data

Playback PAN settings

 Data Name

CPK_SetPan

 No

4.4

Form
void CPK_SetPan (CpkHn cpk, Sint32 pan)
input
cpk: movie handle
pan: PAN value (0 to 31)
output
none
Function value
none
function
Specifies the sound PAN. The default is 0.
 0
 1
 2
 15
 16
 17
 18
 31
 Left
Right
 Max
Max
 >> >>
Max
 >> >>
Max
 >> >>
Max
 Off Off
Max
 Max
Max
 Max
>> >>
 Max
>> >>
 Max
>> >>
 Max
Off Off

 List
 Title

Function specifications

 Data

Playback volume setting

 Data Name

CPK_SetVolume

 No

4.5

Form
void CPK_SetVolume (CpkHn cpk, Sint32 volume)
input
cpk: movie handle
volume: Volume (0-7)
output
none
Function value
none
function
Specify the volume. (0 is no output, 7 is maximum volume) The default is 7.

 List
 Title

Function specifications

 Data

PCM command block number setting

 Data Name

CPK_SetPcmCmdBlock

 No

4.6

Form
voidC PK_SetPcmCmdBlockNo (CpkHn cpk, Sint32 blk_no)
input
cpk: movie handle
blk_no: PCM command block number (0-7)
output
none
Function value
none
function
Set the PCM command block number to be set in the sound driver. The default is 0.
For more information on PCM command block numbers, see SEGA SATURN Sound Driver System Interface.
Call this function before playing the movie.

 List
 Title

Function specifications

 Data

PCM stream playback number setting

 Data Name

CPK_SetPcmStreamNo

 No

4.7

Form
void CPK_SetPcmStreamNo (CpkHn cpk, Sint32 stream_no)
input
cpk: movie handle
stream_no: PCM stream playback number (0-7)
output
none
Function value
none
function
Set the PCM stream playback number to be set in the sound driver. The default is 0.
For more information on PCM stream playback numbers, see SEGA SATURN Sound Driver System Interface.
remarks
When playing multi-motion, use different stream playback numbers. Call this function before playing the movie.

 List
 Title

Function specifications

 Data

Keyout range setting

 Data Name

CPK_SetKeyOutRange

 No

4.8

Form
void CPK_SetKeyOutRange (CpkHn cpk, Sint32 range)
input
cpk: movie handle
range: The range of keyouts (colors to be transparent)
output
none
Function value
none
function
Set the range to be transparent by chroma key processing.
remarks

 List
 Title

Function specifications

 Data

Silence rate setting

 Data Name

CPK_SetSilenceRate

 No

4.9

Form
void CPK_SetSilenceRate (CpkHn cpk, Sint32 silence_rate)
input
cpk: handle
silence_rate: Silence rate [1 / sec] 1 to 15
The default is CPK_DEFAULT_SILENCE_RATE
output
none
Function value
none
remarks
A silence rate of 4 means a quarter second silence setting. Up to 1 second.
If the load other than the Cinepak library is heavy at the end of playback and noise is generated due to lack of silence, you can adjust the silence setting amount to avoid noise.

 List
 Title

Function specifications

 Data

Playback start trigger size setting

 Data Name

CPK_SetStartTrgSize

 No

4.10

Form
void CPK_SetStartTrgSize (CpkHn cpk, Sint32 size)
input
cpk: handle
size: Supply amount to ring buffer [byte]
Data supply larger than this size is a prerequisite for starting playback.
Must be less than (ring buffer size-24 sectors).
Must be less than the playback file size.
The default is CPKLIB_SIZE_TRIGGER (0 byte).
output
none
Function value
none
remarks
Please set before starting playback. This setting still requires CPK_Start or CPK_EntryNext.
The average is about 300 [kbyte / s], and even if the interval exceeds 300 [kbyte / s] to some extent, the fluctuation of the data rate corresponding to this set amount can be tolerated.
This setting improves stability and reduces frame dropping.
However, it is necessary to consider the delay of playback start according to this set amount.

 List
 Title

Function specifications

 Data

Setting CPU usage conditions

 Data Name

CPK_SetCpu

 No

4.11

Form
void CPK_SetCpu (CpkCpu cpu)
input
cpu: CPU usage conditions
argument meaning
 CPK_CPU_MAIN
 Use only SH2 on the master side. (Default)
 CPK_CPU_DUAL
 Use both master and slave SH2.
output
none
Function value
none
remarks
Added support for dual CPU decompression processing. It is not very fast because it is a process that reads and writes a lot of data, but there is an improvement in processing speed of about 15% to 20%.
(Even with 32000 colors, it was measured once by outputting to WORK RAM H)
You can play 320 x 200 [dot] 20 [fps] videos in full color. If the area is small and the frame is not divided (when the number of tiles is 1), dual CPU processing will not be performed.
caution
If you use a slave CPU in Cinepak, your application cannot use the slave CPU.

 List
 Title

Function specifications

 Data

Stream server function call settings

 Data Name

CPK_SetStmServerCall

 No

4.12

Form
void CPK_SetStmServerCall (Bool mode)
input
mode: Call settings
argument meaning
 ON
 The library side calls. (Default)
 OFF OFF
 The application side calls.
output
none
Function value
none
remarks
This function makes sense when playing a stream. This setting allows the application to call the server function.
The following two processes are equivalent.

[Processing A]
 After initialization
 : CPK_SetStmServerCall (ON);
 Regularly during playback
 : CPK_Task (cpkhn);
−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−–
[Processing B]
 After initialization
 : CPK_SetStmServerCall (OFF);
 Regularly during playback
 : STM_ExecServer ();
CPK_Task (cpkhn);

It is effective to avoid excessive STM_ExecServer calls when calling CPK_Task multiple times at the same time in multi-playback or branch playback, or when reading data other than Cinepak from a CD in parallel.
When the application side calls, in some cases STM_ExecTrans can be called instead of STM_ExecServer.
It is not desirable to call STM_ExecServer in CPK_Task due to the modular structure, so it is recommended that the application side call it.

 List
 Title

Function specifications

 Data

Playback speed setting

 Data Name

CPK_SetSpeed

 No

4.13

Form
void CPK_SetSpeed (CpkHn cpk, Sint32 speed, Bool audio_sw)
input
cpk: handle

speed: Playback speed
 argument
 meaning
0
 : Play at normal playback speed. 1x speed. (Default)
1 to 1024
 : Equal speed ratio x 1024
(1024: 1x speed, 512: 1/2 slow, 256: 1/4 slow)

audio_sw: Audio output switch
 argument
 meaning
ON
 : With audio output. (Default)
OFF OFF
 : No audio output. (Volume 0)
output
none
Function value
none
remarks
speed sets the playback speed with a value of equal speed ratio x 1024. 512 is a half and 256 is a quarter slow playback. 0 (zero) specifically means normal playback speed.
The maximum playback speed is the normal playback speed (1024).
The lower limit of the playback speed is as follows depending on the audio frequency of the video.

 Audio frequency
 Lower limit of playback speed
 Equal speed ratio
 44100 [Hz]
 Four
 4/1024 = 1/256
 22050 [Hz]
 8
 8/1024 = 1/128
 11025 [Hz]
 16
 16/1024 = 1/64
 Video only
 1
 1/1024

audio_sw is a switch to turn off the volume while changing the speed. Even if it is turned off, the PCM stream is played internally.
The following constant macros are defined in connection with this function:

CPK_SPEED_ORIGINAL, CPK_SPEED_UNIT

 List
 Title

Function specifications

 Data

Get timescale

 Data Name

CPK_GetTimeScale

 No

5.1

Form
Sint32 CPK_GetTimeScale (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
Time scale
function
Gets the timescale value.
The time scale value is invalid until the data of the film header part is supplied to the ring buffer.

 List
 Title

Function specifications

 Data

Get playback time

 Data Name

CPK_GetTime

 No

5.2.

Form
Sint32 CPK_GetTime (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
Current time
function
Gets the current time of the movie. The current time is a count value in time scale units.

 List
 Title

Function specifications

 Data

Get playback status

 Data Name

CPK_GetPlayStatus

 No

5.3 5.3

Form
CpkPlayStatus CPK_GetPlayStatus (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
Playback status
function
Returns the current playback status of the movie.

 List
 Title

Function specifications

 Data

Get film header

 Data Name

CPK_GetHeader

 No

5.4

Form
CpkHeader * CPK_GetHeader (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
Film header
function
Returns the address of the film header part of the movie file.
The contents of the structure are invalid until the data of the film header part is supplied to the buffer.

 List
 Title

Function specifications

 Data

Acquisition of data stockpile [byte]

 Data Name

CPK_GetStockSize

 No

5.5 5.5

Form
void CPK_GetStockSize (CpkHn cpk, Sint32 * ring_bsize, Sint32 * all_bsize)
input
cpk: handle
output
* ring_bsize: Stockpile [byte] in the ring buffer
* all_bsize: Stockpile [byte] including the amount in the CD block
Function value
none
function
It can be used to determine whether seamlessness can be made safe.
If you do not want the output, specify NULL for its argument.
The memory playback handle does not output all_bsize.

 List
 Title

Function specifications

 Data

Acquisition of data stockpile [timescale]

 Data Name

CPK_GetStockTime

 No

5.6

Form
void CPK_GetStockTime (CpkHn cpk, Sint32 * ring_time, Sint32 * all_time)
input
cpk: handle
output
* ring_bsize: Stockpile in the ring buffer [timescale]
* all_bsize: Stockpile including the amount in the CD block [timescale]
Function value
none
function
It can be used to determine whether seamlessness can be made safe.
If you do not want the output, specify NULL for its argument.
The memory playback handle does not output all_time.
caution
After creating a handle, if the task function is called without starting, there may be a stockpile in the ring buffer, but if header processing has not been performed yet, it cannot be checked, so 0 is returned. CPK_GetStockSize will give you a valid value in this situation as well.

 List
 Title

Function specifications

 Data

Get write buffer

 Data Name

CPK_GetWriteBuf

 No

6.1

Form
Uint32 * CPK_GetWriteBuf (CpkHn cpk, Sint32 * free_size, Sint32 * free_total)
input
cpk: movie handle
output
free_size: Number of bytes in the area that can be continuously written
free_total: Total number of bytes in the writable area including the discontinuous area
Function value
Start address of continuously writable area (NULL if not writable)
function
Gets the buffer address to write to and the number of bytes that can be written.
remarks
It is used when you want to supply data to the ring buffer independently.

 List
 Title

Function specifications

 Data

Write size notification

 Data Name

CPK_NotifyWriteBuf

 No

6.2.

Form
void CPK_NotifyWriteSize (CpkHn cpk, Sint32 write_size)
input
cpk: movie handle
write_size: number of bytes written
output
none
Function value
none
function
Notifies the library of the number of bytes actually written to the buffer.
remarks
It is used when you want to supply data to the ring buffer independently.
Used when playing a movie file in memory.

 List
 Title

Function specifications

 Data

Load the movie into the buffer

 Data Name

CPK_PreloadMovie

 No

7.1

Form
void CPK_PreloadMovie (CpkHn cpk, Uint32 size)
input
cpk: movie handle
size: number of bytes to read
output
none
Function value
none
function
Load the movie file into memory.
remarks
If the number of bytes read is smaller than the buffer managed by the library, read up to the buffer size.

 List
 Title

Function specifications

 Data

Load the film header into the buffer

 Data Name

CPK_PreloadHeader

 No

7.2

Form
void CPK_PreloadHeader (CpkHn cpk)
input
cpk: movie handle
output
none
Function value
none
function
Reads the film header part of the movie file into memory.
remarks
Before calling this function, move the pickup position to the beginning of the movie file.

 List
 Title

Function specifications

 Data

Get error information

 Data Name

CPK_GetErr

 No

8.1

Form
CpkErrCode CPK_GetErr (void)
input
none
output
none
Function value
Error code
function
Returns the most recently generated error code.

 List
 Title

Function specifications

 Data

Error function registration

 Data Name

CPK_SetErrFunc

 No

8.2. 8.2

Form
void CPK_SetErrFunc (CpkErrFunc func, void * obj)
input
func: Function to call when an error occurs
obj: Registered object
output
none
Function value
none
function
Set the function to be called when an error occurs. The registration object is passed to the first argument of the registration function.

 List
 Title

Function specifications

 Data

Securing SCU-DSP resources

 Data Name

CPK_AllocScuDsp

 No

9.1

Form
Sint32 CPK_AllocScuDsp (void)
input
output
none
Function value
 argument
 meaning
 OK
 : SCU-DSP is secured on the application side.
(Including when the library was not used)
 NG
 : The library is in use and cannot be secured now.
remarks
Use CPK_AllocScuDsp, CPK_FreeScuDsp when using SCU-DSP with both the Cinepak library and the application.
If CPK_TRMODE_SCUDSPDMA is specified as the forwarding method, the Cinepak library initially has the right to use SCU-DSP.
Applications can temporarily use SCU-DSP only when the Cinepak library is not using SCU-DSP, that is, when the return value of CPK_AllocScuDsp is OK.
If the Cinepak library returns OK with CPK_AllocScuDsp, it will suspend processing using SCU-DSP until CPK_FreeScuDsp is subsequently called.
Therefore, if you keep it for a long time, playback may be delayed.
Since the contents of the DSP program are not guaranteed due to the transfer of usage rights, the application side also needs to load the DSP program each time.
This function must not be called by interrupt processing while the task function is operating.

 List
 Title

Function specifications

 Data

Release of SCU-DSP resources

 Data Name

CPK_FreeScuDsp

 No

9.2

Form
void CPK_FreeScuDsp (void)
input
none
output
none
Function value
none
remarks
See CPK_AllocScuDsp.


BackForward
MOVIE TOOLS GUIDECinepak for SEGA Saturn
Copyright SEGA ENTERPRISES, LTD ,. 1997