Japanese
MOVIE TOOLS GUIDECinepak for SEGA Saturn
BackForward
Cinepak for SEGASaturn


4.6 Function details

 one
View
table
 Title

function specification

 Data

Initialization

 Data Name

CPK_Init

 No

1.1

Format
Bool CPK_Init(void)
input
none
output
none
function value
TRUE if initialization was successful
FALSE if unable to initialize successfully
function
Immediately after starting the program, initialization is performed to use this library.
remarks
When using this library, be sure to call this function at the beginning of the program.

 one
View
table
 Title

function specification

 Data

End processing

 Data Name

CPK_Finish

 No

1.2

Format
void CPK_Finish(void)
input
none
output
none
function value
none
function
If you do not want to play the movie again, call this function.

 one
View
table
 Title

function specification

 Data

Creating a handle (memory)

 Data Name

CPK_CreateMemMovie

 No

2.1

Format
CpkHn CPK_CreateMemMovie(CpkCreatePara *para)
input
para: creation parameter
output
none
function value
Movie handle (NULL if cannot be created)
function
Creates a movie handle to play a movie file in memory.
remarks

 one
View
table
 Title

function specification

 Data

Erasing handles (memory)

 Data Name

CPK_DestroyMemMovi

 No

2.2

Format
void CPK_DestroyMemMovie(CpkHn cpk)
input
cpk: movie handle
output
none
function value
none
function
Erase the movie handle.
Once you clear a handle, you can no longer use the movie handle.

 one
View
table
 Title

function specification

 Data

Creating a handle (file system)

 Data Name

CPK_CreateGfsMovie

 No

2.3

Format
CpkHn CPK_CreateGfsMovie(CpkCreatePara *para, GfsHn gfs)
input
para: creation parameter
gfs: file handle
output
none
function value
Movie handle (NULL if cannot be created)
function
Creates a movie handle to play a movie file on the file system.
remarks

 one
View
table
 Title

function specification

 Data

Clearing a handle (file system)

 Data Name

CPK_DestroyGfsMovi

 No

2.4

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

 one
View
table
 Title

function specification

 Data

Creating a handle (stream system)

 Data Name

CPK_CreateStmMovie

 No

2.5

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

 one
View
table
 Title

function specification

 Data

Clearing handles (stream system)

 Data Name

CPK_DestroyStmMovi

 No

2.6

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

 one
View
table
 Title

function specification

 Data

replay task

 Data Name

CPK_Task

 No

2.7

Format
void CPK_Task(CpkHn cpk)
input
cpk: movie handle
output
none
function value
none
function
Loads files from CD and expands images.
If you specify NULL for cpk, the play task will be executed for all the handles that are being played.
remarks
Please call this function periodically while the movie is playing.
Please set the calling interval to be greater than the number of playback frames. If the number of frames is less than that, smooth playback will not be possible.
After reading this function, be sure to check whether the display timing is set using CPK_IsDispTime. If CPK_IsDispTime returns TRUE, the timer to display the image  Since it is processing, please change the frame if it has been expanded to sprite VRAM. If it was expanded to memory, please transfer it to VRAM. Be sure to call CPK_CompleteDisp afterwards.
Please note that if you specify the destination address in VRAM, the data will be expanded before the display timing.

 one
View
table
 Title

function specification

 Data

Determining display timing

 Data Name

CPK_IsDispTime

 No

2.8

Format
Bool CPK_IsDispTime(CpkHn cpk)
input
cpk: movie handle
output
none
function value
TRUE when the movie frame image has been expanded and it is time to display it.
FALSE if it is not yet time to display
function
If this function returns TRUE, it is time to display one frame of image, so if it was expanded to sprite VRAM, change the frame. If it was expanded to memory, transfer the expanded contents to VRAM. Be sure to call CPK_CompleteDisp afterward.

 one
View
table
 Title

function specification

 Data

Display completion notification

 Data Name

CPK_CompleteDisp

 No

2.9

Format
void CPK_CompleteDisp(CpkHn cpk)
input
cpk: movie handle
output
none
function value
none
function
Notifies the library that the image display has finished.
remarks
Please call this function when CPK_IsDispFrame becomes TRUE. If you do not call it, the movie will not play.

 one
View
table
 Title

function specification

 Data

V blank IN processing function

 Data Name

CPK_VblIn

 No

2.10

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

 one
View
table
 Title

function specification

 Data

Start playing

 Data Name

CPK_Start

 No

3.1

Format
void CPK_Start(CpkHn cpk)
input
cpk: movie handle
output
none
function value
none
function
Start playing the movie.
remarks
A movie can only be played once for a generated movie handle.
If you want to play the same movie over and over again, generate a movie handle each time.

 one
View
table
 Title

function specification

 Data

Stop playing

 Data Name

CPK_Stop

 No

3.2

Format
void CPK_Stop(CpkHn cpk)
input
cpk: movie handle
output
none
function value
none
function
Stop playing the movie.

 one
View
table
 Title

function specification

 Data

Pause

 Data Name

CPK_Pause

 No

3.3

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

Returns FALSE if:

function value
none
function
Pause or cancel movie playback.

 one
View
table
 Title

function specification

 Data

Registering the next movie to play

 Data Name

CPK_EntryNext

 No

3.4

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

 one
View
table
 Title

function specification

 Data

Forced movie switching

 Data Name

CPK_Change

 No

3.5

Format
void CPK_Change(void)
input
none
output
none
function value
none
function
Interrupts the currently playing movie and starts playing the movie registered in CPK_EntryNext.

 one
View
table
 Title

function specification

 Data

Obtaining movie switching status

 Data Name

CPK_CheckChange

 No

3.6

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

 one
View
table
 Title

function specification

 Data

Expand specified frame

 Data Name

CPK_DecodeFrame

 No

3.7

Format
void CPK_DecodeFrame(CpkHn cpk, Sint32 frame_no)
input
cpk: movie handle
frame_no: Number of frame to expand
output
none
function value
none
function
Expands the image in the specified frame.
remarks
This function can only be used for movies loaded into 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 movie handles created with CPK_CreateGfsMovie and CPK_CreateStmMovie.
Please use a movie file with only keyframes and no sound.

 one
View
table
 Title

function specification

 Data

Expand specified frame
(Differential frame guarantee)

 Data Name

CPK_DecodeFrameSafety

 No

3.8

Format
void CPK_DecodeFrameSafety(CpkHn cpk, Sint32 sample_no)
input
cpk: handle
sample_no: Sample number
output
none
function value
none
function
Expands the image in the specified frame.
remarks
CPK_DecodeFrameSafety processes back to the keyframe in the case of a differential frame and outputs the correct image. Use this when randomly accessing a movie containing differential frames.
Note
Please load it in advance and use it for memory playback.
If it does not contain audio, the frame number is the sample number. If audio is included, make sure that the sample number you specify is not an audio sample. Please refer to smpcpk7.c as there is a process to obtain the sample number from the frame number.

 one
View
table
 Title

function specification

 Data

Setting the destination address

 Data Name

CPK_SetDecodeAddr

 No

4.1

Format
void CPK_SetDecodeAddr(CpkHn cpk, void *dec_addr, Sint32 dec_line_size)
input
cpk: movie handle
dec_addr: Address of image expansion destination
dec_line_size: Number of bytes in one line of image expansion destination buffer
output
none
function value
none
function
Specify the address to transfer the expanded image.
If the image expansion destination address is NULL, image expansion will not be performed. Default is NULL.
Please call this function before playing the movie.

 one
View
table
 Title

function specification

 Data

Setting the number of display colors

 Data Name

CPK_SetColor

 No

4.2

Format
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 colors displayed in the image. Default is 16 million colors.
Please call this function before playing the movie.

 one
View
table
 Title

function specification

 Data

Setting the maximum number of transferred sectors

 Data Name

CPK_SetLoadNum

 No

4.3

Format
void CPK_SetLoadNum(CpkHn cpk, Sint32 load_sct)
input
cpk: movie handle
load_sct: Maximum number of transferred sectors
output
none
function value
none
function
Set the maximum number of transfer sectors when transferring from the CD buffer to the library's internal buffer. Default is 20 sectors.
Please call this function before playing the movie.

 one
View
table
 Title

function specification

 Data

Playback PAN settings

 Data Name

CPK_SetPan

 No

4.4

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

 one
View
table
 Title

function specification

 Data

Setting playback volume

 Data Name

CPK_SetVolume

 No

4.5

Format
void CPK_SetVolume(CpkHn cpk, Sint32 volume)
input
cpk: movie handle
volume: Volume (0 to 7)
output
none
function value
none
function
Specify the volume. (0 = no output, 7 = maximum volume) Default is 7.

 one
View
table
 Title

function specification

 Data

Setting PCM command block number

 Data Name

CPK_SetPcmCmdBlock

 No

4.6

Format
voidC PK_SetPcmCmdBlockNo(CpkHn cpk, Sint32 blk_no)
input
cpk: movie handle
blk_no: PCM command block number (0 to 7)
output
none
function value
none
function
Set the PCM command block number to be set in the sound driver. Default is 0.
For more information on PCM command block numbers, see SEGASATURN Sound Driver System Interface.
Please call this function before playing the movie.

 one
View
table
 Title

function specification

 Data

Setting the PCM stream playback number

 Data Name

CPK_SetPcmStreamNo

 No

4.7

Format
void CPK_SetPcmStreamNo(CpkHn cpk, Sint32 stream_no)
input
cpk: movie handle
stream_no: PCM stream playback number (0 to 7)
output
none
function value
none
function
Set the PCM stream playback number to be set in the sound driver. Default is 0.
For more information on PCM stream playback numbers, see SEGASATURN Sound Driver System Interface.
remarks
When playing multi-movies, use different stream playback numbers for each movie. Please call this function before playing the movie.

 one
View
table
 Title

function specification

 Data

Setting the key out range

 Data Name

CPK_SetKeyOutRange

 No

4.8

Format
void CPK_SetKeyOutRange(CpkHn cpk, Sint32 range)
input
cpk: movie handle
range: Key out (transparent color) range
output
none
function value
none
function
Set the range of transparent colors in chroma key processing.
remarks

 one
View
table
 Title

function specification

 Data

Silence rate setting

 Data Name

CPK_SetSilenceRate

 No

4.9

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

 one
View
table
 Title

function specification

 Data

Setting the playback start trigger size

 Data Name

CPK_SetStartTrgSize

 No

4.10

Format
void CPK_SetStartTrgSize(CpkHn cpk, Sint32 size)
input
cpk:handle
size: Supply amount to ring buffer [byte]
A 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.
Default is CPKLIB_SIZE_TRIGGER (0 byte).
output
none
function value
none
remarks
Please set before starting playback. Even with this setting, CPK_Start or CPK_EntryNext is still required.
The average is about 300[kbyte/s], and even if there are sections that exceed 300[kbyte/s] to some extent, it will be possible to tolerate fluctuations in the data rate equivalent to this setting amount.
This setting improves stability and reduces the chance of dropped frames.
However, you must consider the delay in the start of playback depending on this setting amount.

 one
View
table
 Title

function specification

 Data

Setting CPU usage conditions

 Data Name

CPK_SetCpu

 No

4.11

Format
void CPK_SetCpu(CpkCpu cpu)
input
cpu :CPU usage conditions
argument meaning
 CPK_CPU_MAIN
 Only SH2 on the master side is used. (Default)
 CPK_CPU_DUAL
 Use both master and slave SH2.
output
none
function value
none
remarks
Supports dual CPU decompression processing. The processing speed will not be much faster because it involves a lot of reading and writing of data, but the processing speed will be improved by about 15% to 20%.
(Even for 32000 colors, measurements were made by first outputting to WORK RAM H.)
You can play 320×200[dot] 20[fps] videos in full color. If the area is small and the frame is not divided (the number of tiles is 1), dual CPU processing will not be possible.
Note
When using a slave CPU with Cinepac, applications cannot use the slave CPU.

 one
View
table
 Title

function specification

 Data

Stream server function call settings

 Data Name

CPK_SetStmServerCall

 No

4.12

Format
void CPK_SetStmServerCall(Bool mode)
input
mode: call settings
argument meaning
 ON
 Library side calls. (Default)
 OFF
 Application side calls.
output
none
function value
none
remarks
This function has meaning when performing stream playback. This setting allows the application to call server functions.
The following two processes are equivalent.

[Processing A]
 after initialization
 :CPK_SetStmServerCall(ON);
 Periodically during playback
 : CPK_Task (cpkhn);
−−−−−−−−−−−−−−−−−−−−−−−−−−−−
[Processing B]
 after initialization
 :CPK_SetStmServerCall(OFF);
 Periodically during playback
 : STM_ExecServer ();
CPK_Task (cpkhn);

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

 one
View
table
 Title

function specification

 Data

Setting playback speed

 Data Name

CPK_SetSpeed

 No

4.13

Format
void CPK_SetSpeed(CpkHn cpk, Sint32 speed, Bool audio_sw)
input
cpk : Handle

speed: playback speed
 argument
 meaning
0
 : Play at normal playback speed. Same speed. (Default)
1~1024
 : Constant speed ratio x 1024
(1024: Normal speed, 512: 1/2 slow, 256: 1/4 slow)

audio_sw :Audio output switch
 argument
 meaning
ON
 : Audio output available. (Default)
OFF
 : No audio output. (Volume 0)
output
none
function value
none
remarks
speed sets the playback speed with the value of constant speed ratio x 1024. 512 slows playback to 1/2, 256 slows playback to 1/4. 0 (zero) specifically means normal playback speed.
The upper limit of playback speed is normal playback speed (1024).
The minimum playback speed is determined by the audio frequency of the video as follows:

 audio frequency
 Lower limit of playback speed (speed)
 Constant speed ratio
 44100[Hz]
 4
 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 speed. Even if it is turned off, PCM stream playback is performed internally.
The following constant macros are defined in relation to this function:

CPK_SPEED_ORIGINAL, CPK_SPEED_UNIT

 one
View
table
 Title

function specification

 Data

Get timescale

 Data Name

CPK_GetTimeScale

 No

5.1

Format
Sint32 CPK_GetTimeScale(CpkHn cpk)
input
cpk: movie handle
output
none
function value
time scale
function
Get the timescale value.
The time scale value is invalid until the film header data has been supplied to the ring buffer.

 one
View
table
 Title

function specification

 Data

Get playback time

 Data Name

CPK_GetTime

 No

5.2

Format
Sint32 CPK_GetTime(CpkHn cpk)
input
cpk: movie handle
output
none
function value
current time
function
Get the current time of the movie. The current time is a count value in timescale units.

 one
View
table
 Title

function specification

 Data

Get playback status

 Data Name

CPK_GetPlayStatus

 No

5.3

Format
CpkPlayStatus CPK_GetPlayStatus(CpkHn cpk)
input
cpk: movie handle
output
none
function value
playback status
function
Returns the movie's current playback status.

 one
View
table
 Title

function specification

 Data

Get film header

 Data Name

CPK_GetHeader

 No

5.4

Format
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 film header data has been supplied to the buffer.

 one
View
table
 Title

function specification

 Data

Acquisition of data storage amount [byte]

 Data Name

CPK_GetStockSize

 No

5.5

Format
void CPK_GetStockSize(CpkHn cpk, Sint32 *ring_bsize, Sint32 *all_bsize)
input
cpk:handle
output
*ring_bsize: Reserved amount in ring buffer [byte]
*all_bsize: Storage amount including the amount in CD block [byte]
function value
none
function
This can be used to determine whether seamlessness can be achieved safely.
If no output is required, specify NULL for that argument.
all_bsize is not output for memory reclamation handles.

 one
View
table
 Title

function specification

 Data

Obtain data storage amount [timescale]

 Data Name

CPK_GetStockTime

 No

5.6

Format
void CPK_GetStockTime(CpkHn cpk, Sint32 *ring_time, Sint32 *all_time)
input
cpk:handle
output
*ring_bsize: Reserved amount in ring buffer [timescale]
*all_bsize: Reserved amount including the amount in CD block [timescale]
function value
none
function
This can be used to determine whether seamlessness can be achieved safely.
If no output is required, specify NULL for that argument.
All_time is not output for memory reclamation handles.
Note
If the task function is called without starting after the handle is created, there may be some reserves in the ring buffer, but if the header has not been processed yet, it cannot be checked and 0 is returned. With CPK_GetStockSize , you can get a valid value even in this situation.

 one
View
table
 Title

function specification

 Data

Get write buffer

 Data Name

CPK_GetWriteBuf

 No

6.1

Format
Uint32 *CPK_GetWriteBuf(CpkHn cpk, Sint32 *free_size, Sint32 *free_total)
input
cpk: movie handle
output
free_size: Number of bytes of area that can be written continuously
free_total: Total number of bytes of writable area including non-contiguous areas
function value
Start address of continuous writable area (NULL if writable is not possible)
function
Get the buffer address to write to and the number of bytes that can be written.
remarks
Use this when you want to independently supply data to the ring buffer.

 one
View
table
 Title

function specification

 Data

Write size notification

 Data Name

CPK_NotifyWriteBuf

 No

6.2

Format
void CPK_NotifyWriteSize(CpkHn cpk, Sint32 write_size)
input
cpk: movie handle
write_size: Number of bytes written
output
none
function value
none
function
Tells the library how many bytes were actually written to the buffer.
remarks
Use this when you want to independently supply data to the ring buffer.
Used when playing movie files in memory.

 one
View
table
 Title

function specification

 Data

Load movie into buffer

 Data Name

CPK_PreloadMovie

 No

7.1

Format
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.

 one
View
table
 Title

function specification

 Data

Load film header into buffer

 Data Name

CPK_PreloadHeader

 No

7.2

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

 one
View
table
 Title

function specification

 Data

Get error information

 Data Name

CPK_GetErr

 No

8.1

Format
CpkErrCode CPK_GetErr(void)
input
none
output
none
function value
Error code
function
Returns the most recent error code.

 one
View
table
 Title

function specification

 Data

Registering an error function

 Data Name

CPK_SetErrFunc

 No

8.2

Format
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 as the first argument of the registration function.

 one
View
table
 Title

function specification

 Data

Securing SCU-DSP resources

 Data Name

CPK_AllocScuDsp

 No

9.1

Format
Sint32 CPK_AllocScuDsp(void)
input
output
none
function value
 argument
 meaning
 OK
 :SCU-DSP is reserved on the application side.
(Including cases where the library is not using it)
 NG
 :The library is in use, so it cannot be secured now.
remarks
Use CPK_AllocScuDsp and CPK_FreeScuDsp when using SCU-DSP with both Cinepak library and application.
If CPK_TRMODE_SCUDSPDMA is specified as the transfer method, the SCU-DSP usage rights are initially in the Cinepak library.
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 CPK_AllocScuDsp returns OK, the Cinepak library suspends processing using SCU-DSP until CPK_FreeScuDsp is called.
Therefore, if you leave it in a secured state for a long time, playback may be delayed.
When the usage rights are transferred, the contents of the DSP program are no longer guaranteed, so the application side must also load the DSP program each time.
This function must not be called for interrupt processing while the task function is running.

 one
View
table
 Title

function specification

 Data

Releasing SCU-DSP resources

 Data Name

CPK_FreeScuDsp

 No

9.2

Format
void CPK_FreeScuDsp(void)
input
none
output
none
function value
none
remarks
See CPK_AllocScuDsp .


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