<9/11> Cinepak for SEGA Saturn User's Manual

★ MOVIE TOOLS GUIDE ★ Cinepak for SEGA Saturn

▲ Back ｜ Forward ▼

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
You can create 32 movies at the same time.
Load the movie file into memory with the application program.
For the movie handle generated by CPK_CreateMemMovie, be sure to notify the size of the movie file with CPK_NotifyWriteSize.

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
You can create 32 movies at the same time.
Obtain the file handle with the application program in advance.

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
Erase the movie handle.
Once you erase a handle, that movie handle can no longer be used.
Erase the movie handle before closing the file handle.

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
You can create 32 movies at the same time.
Obtain the stream handle in the application program in advance.

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
Erase the movie handle.
Once you erase a handle, that movie handle can no longer be used.
Erase the movie handle before closing the stream handle.

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:

Handle abnormality.
Attempted to pause with a playback status other than CPK_STAT_PLAY_TIME.
Playback status An attempt was made to unpause other than CPK_STAT_PLAY_PAUSE.
I tried to pose during the next move to the movie.

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
In chroma key processing, the RGB value of the expanded point and the RGB value specified by the chroma key are compared by the following formula, and if the value is smaller than the keyout range, the color is made transparent.
ABS (ckey.b --decode.b) + ABS (ckey.g --decode.g) + ABS (ckey.r --decode.r) ckey is the chroma key The specified RGB value decode is the RGB value of the expanded point

For 32000 colors, you can specify a range from 0 to 96.
For 16 million colors, you can specify a range from 0 to 768.
The default is 21.

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);
[Processing A]	Regularly during playback	: CPK_Task (cpkhn);
[Processing B]	After initialization	: CPK_SetStmServerCall (OFF);
[Processing B]	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.

▲ Back ｜ Forward ▼

★ MOVIE TOOLS GUIDE ★ Cinepak for SEGA Saturn