<5/11> Cinepak for SEGA Saturn User's Manual / 4. Cinepak library

★ MOVIE TOOLS GUIDE ★ Cinepak for SEGA Saturn

▲ Back ｜ Forward ▼

Cinepak for SEGA Saturn / 4. Cinepak library

4.3 Programming Precautions

Here are some things to keep in mind when playing videos using the Cinepak library:

(1) Precautions for creating applications

For the buffer address (CPK_PARA_WORK_ADDR, CPK_PARA_BUF_ADDR of CpkCreatePara) specified when creating a movie, specify the WORK_RAM-H area (06000000H ~). Specifying a slow RAM area will slow down Cinepak's performance. The Cinepak library uses CPU DMA and timers. Do not use CPU DMA and timer during Cinepak operation. If the same sound is heard twice, it is possible that the CPK_Task is called too few times or the image size is too large. Call CPK_Task frequently or reduce the image size.

(2) Relationship with other libraries

This library uses a file system, stream system, and DMA library. Link these files.

(3) How to take a buffer

The size of the ring buffer has a lot to do with the sound content. The higher the quality of the sound, the more buffers you will need. Specifically, secure a minimum of the header size of the movie file + the size of 0.5 seconds of sound + 80KB. The larger the ring buffer, the lighter the Cinepak process.
"example"
Movie 1 minute, 44KHz at 30fps, 16 bits, ring buffer size ≧ 32KB ＋ 88KB ＋ 80KB ＝ 200KB for stereo
Movie 1 minute, 30fps, 11KHz, 8 bits, monaural Ring buffer size ≧ 32KB ＋ 5.5KB ＋ 80KB ＝ 117.5KB
The buffer size of the sound memory (CPK_PARA_PCM_SIZE of CpkCreatePara) of the parameter at the time of movie generation is the number of PCM quantizations for one channel.
Specify an integer multiple of 4096. The range is 4096 * 4 to 4096 * 16.
For the buffer size, specify the number of PCM quantizations of 1.4 seconds or more.
"example"
If the sampling frequency is 44kHz, set the buffer size to 64K.
If the sampling frequency is 22kHz, set the buffer size to 32K or higher.

(4) Chroma key processing

Chroma key processing will slightly increase the processing time of CPK_Task. When using chroma key processing, set the transparent pixel invalid bit of the sprite command to 0. If you want to change the range to be transparent in the chroma key processing, change the range with the keyout (color to be transparent) range setting function (CPK_SetKeyOutRange).

(5) Seamless branch

When seamlessly branched with CPK_EntryNext, the PCM volume and PAN will be the same as the previous movie. When seamlessly branching with CPK_EntryNext, you can play continuously for up to 60 minutes. No further continuous playback is possible. Start playing the movie once with CPK_Start. For seamless branching, use the application program to pre-read the movie file. If you use a file system, you cannot use the seamless branch function. Seamless branching can only be done during one movie playback. It cannot be executed during multi-motion playback.

(6) Multi-motion playback

When playing multi-motion, set the PCM stream playback number to a different number. If you want to play multiple videos on a CD at the same time, use file interleaving or channel interleaving. In that case, use the stream system. The same file cannot be played in multi-motion. Please specify a different file. You can play up to 4 multi-moves at the same time.

(7) Expansion of designated frame

When using the specified frame expansion (CPK_DecodeFrame), use a movie file with only keyframes without sound. Use the file system or stream system in the application program to load the movie file into memory before decompressing it. Use CPK_CreateMemMovie.

(8) Use of functions

Be sure to call CPK_Init at the beginning of your program. Be sure to call CPK_VblIn in the V-blank IN interrupt. Before using CPK_GetTimeScale and CPK_GetHeader, read the header part of the movie. CPK_Start can only be run once on a movie handle. If you want to play the same movie file many times, generate a movie handle each time. Call CPK_SetDecodeAddr, CPK_SetColor, CPK_SetLoadNum, CPK_SetPcmCmdBlockNo, CPK_SetPcmStreamNo before playing the movie. After calling CPK_Task, be sure to use CPK_IsDispTime to check if the display timing is set. Whenever CPK_IsDispTime returns TRUE, then be sure to call CPK_CompleteDisp. For the movie handle generated by CPK_CreateMemMovie, be sure to notify the size of the movie file with CPK_NotifyWriteSize.

(9) Error handling

If an error occurs in the file system or stream system during movie playback, movie playback cannot continue after that. In this case, delete the movie handle and close the file. After that, perform processing such as playing the movie again.
Be sure to set each error handling function GFS_SetErrFunc, STM_SetErrFunc, CPK_SetErrFunc to detect an error. It also improves debugging efficiency.

(10) Precautions when using SCU-DMA

When data transfer from the CD block to the ring buffer is performed by DMA of the SCU, peripheral information may not be obtained correctly.
In this case, you can improve by setting the maximum number of transfer sectors (default value 20) small, but if you set it small, you need to call the task function frequently enough to match it.

[Processing example]

CPK_SetTrModeCd (cpk, CPK_TRMODE_SCU); / * Transfer by SCU-DMA * /
CPK_SetLoadNum (cpk, 10); / * Maximum value of one transfer [Sector] * /

Also, during transfer with SCU-DMA, the bus to be used is occupied, so SH will be in a weighted state from the time you try to access the CPU bus. Do not use SCU-DMA as much as possible.

(11) About change of registration of next handle

CPK_EntryNext is designed to cancel the previous registration if you call it again before switching. However, this cannot be canceled if the processing of the next handle has started internally just before switching.
The application can determine this transition period from the playback status of the next handle.

if (CPK_GetPlayStatus (cpk_now) == CPK_STAT_PLAY_TIME) {
	if (CPK_GetPlayStatus (cpk_next)! = CPK_STAT_PLAY_STOP) {

		/ * It's in the transition period to the next handle, so never * /
		/ * Do not call CPK_EntryNext. * /

	} else {

		/ * Since the processing of the next handle has not started yet * /
		/ * It is possible to change the registration of the next handle. * /
		/ * Please refer to [Caution]. * /

	}
} else {

	/ * It has already been switched to the registered handle. * /
	/ * It is possible to register the next handle. * /

}

There are two possible ways to regenerate the desired handle during the transition to the next handle.

How to keep seamless during the transition period In this situation, in order to switch seamlessly and without static screen, wait for the next handle to start playing, CPK_EntryNext, and CPK_CheckChange to supply enough data. Check and switch with CPK_Change.
How to force a switch during the transition period If you don't need seamlessness, stop (erase) the playing and next handles and start playing the handle you want to play with CPK_Start, or with CPK_EntryNext and CPK_Change.

【caution】

Whether or not switching can be done seamlessly is affected by the seek time for reading the data of the next handle, etc., so the Cinepak library cannot guarantee it.
In the above judgment processing example, "Since the processing of the next handle has not started yet, it is possible to change the registration of the next handle." Means that there is no problem in using the Cinepak library. Therefore, this criterion may not be seamless.

To be completely seamless when changing registrations, make sure that you can estimate the remaining playback time of the data stored in the currently replaying handle and seek and read in less time. If it cannot be done, do not change the registration, wait for the handle to move, and switch using the method (1.).
It is difficult to make this exact decision, but CPK_GetStockSize and CPK_GetStockTime can be used to estimate stockpiles, and seek and read times can be safe with the worst possible times.

(12) Relationship between frame size and Cinepak compression method

Cinepak divides one frame into 1 to 3 and performs compression processing according to the frame size (area).
Before and after the condition of division, the internal compression efficiency and image quality become discontinuous, and it is thought that there are the following tendencies.

If it is smaller than the division condition and close to the division condition: Image quality is poor (compression rate is a little good)
If it is larger than the division condition and close to the division condition: Image quality is good (compression rate is a little bad)

The exact division conditions are unknown, but the confirmed range is shown below.

Area [pixel]	Number of frame divisions (number of tiles)
96000 = 480 x 200 or more	3
95744 = 352 × 272 or less 59904 = 208 x 288 or more	2
57344 = 256 × 224 or less	1 (Do not divide)

* Cinepak library supports less than 2 divisions.

(13) Efficiency of image expansion processing

Since it is more efficient to output the image expansion process to WORK RAM-H than to output it directly to VRAM, the task function operates faster.
If you output to WORK RAM-H and transfer it to VRAM with SCU-DMA, the processing time will be shorter even if you add the transfer time.

(14) Supports uncompressed video

Overview You can now play 24-bit uncompressed movies. It is used when you want to reduce the image size and frame rate and give priority to image quality.
It does not support 15-bit color movies, it supports 32,000-color display of 24-bit data, but it wastes high-quality data.
Convert uncompressed QuickTime Movie with MovieToSaturn_J. No functions have been added for playing uncompressed movies. Since the file header is interpreted and processed, it can be played with exactly the same procedure. However, only the ring buffer must be reserved larger than when compressed.
Ring buffer size The ring buffer must be secured to meet the following conditions.
ring ≧ header + sound + frame
ring: Ring buffer size header: File header size (rounded up to the sector size boundary) sound: Sound 0.5 seconds size frame: 1 frame uncompressed size
Video performance Based on the data transfer rate from the CD, the video performance will be as shown below.
Audio conditions Marginal video performance
44kHz, 16bit, stereo
320 × 224 [dot] 0.60 [fps]
22kHz, 8bit, monaural
320 × 224 [dot] 1.32 [fps]
Video only movie
320 × 224 [dot] 1.42 [fps]
Video only movie
160 × 112 [dot] 5.71 [fps]

(15) Execution history output for debugging

Audio conditions	Marginal video performance
44kHz, 16bit, stereo	320 × 224 [dot] 0.60 [fps]
22kHz, 8bit, monaural	320 × 224 [dot] 1.32 [fps]
Video only movie	320 × 224 [dot] 1.42 [fps]
Video only movie	160 × 112 [dot] 5.71 [fps]

Outputs the execution history of the main processes of the Cinepak library.
It is useful for investigating the cause when there is a malfunction such as not being able to play smoothly.
You can check whether task calls are made regularly, data supply is not interrupted, and frames are dropped.
It is easier to analyze the history by making a simpler execution history after confirming the reproducibility of the malfunction.

[Internal processing of Cinepak library that outputs history]

When an error occurs, when a task function is called, when ring buffer data is supplied and consumed, when the display request flag is ON / OFF, time-lapse processing, PCM start / stop

[Specify output]

・ When using the production program as it is

Breaks after processing CPK_Init.
Look up the address of the CpkdSys type structure cpkd_sys in the map file created at link time, and set the value of cpkd_sys.mode to 0x00000001 with the ICE command.

: m 060XXXXX 1; l

The output address will be 0x04000000 to 0x047fffff.

-When creating a program for debug output , set CPKD_SetMode (ON) after CPK_Init.
You can set the output address with CPKD_SetPrintAddr.
With CPKD_PrintStr and CPKD_PrintData, it is possible to add and output the execution history of the processing on the application side. When outputting additional data, make the output size an integral multiple of 16 bytes to make the history information easier to read.

[Check output information]

Dump the output address with the ICE command. Saving the displayed content as a text file and viewing it with a text editor makes it easier to analyze the behavior.

:> hist.txt [RET]
: d 04000000 04001000; l [RET]
:>-[RET]

[Format output information]

======== + ========================================= === +
ADDRESS: 0 1 2 3 4 5 6 7 8 9 ABCDEF:
======== + ========================================= === +
04000000: AAAA_AAAA ---- ---- ---- ---- ---- ----:
04000010: "Err" ---- VVVV ---- ---- EEEE_EEEE: Error 
04000020: "Task" PPPP VVVV HHHH_HHHH CCCC_CCCC: start of CPK_MeTask
04000030: "RWri" WWWW VVVV HHHH_HHHH DDDD_DDDD: WRIte Ringbuffer
04000040: "RRea" RRRR VVVV HHHH_HHHH DDDD_DDDD: REAd Ringbuffer
04000050: "DOn" FFFF VVVV LLLL_LLLL TTTT_TTTT: set Disp flag On
04000060: "DOff" FFFF VVVV HHHH_HHHH TTTT_TTTT: set Disp flag Off
04000070: "PcmS" MODE VVVV HHHH_HHHH ADDR SIZE: PCM Start
04000080: "PcmE" MODE VVVV HHHH_HHHH ---- ----: PCM Stop
04000090: "LosF" FFFF VVVV LFLF_LFLF SSSS_SSSS: LOse Frame
        ::
        ::

[Description of output information]

AAAA_AAAA: Current history information output address.
---- VVVV: Vbl counter. You can see the approximate time.
EEEE_EEEE: Error code.
PPPP ----: Playback status [-1, 0, 1, 2, 3, 4, 5].
HHHH_HHHH: Cinepak handle.
CCCC_CCCC: Cinepak task call counter.
DDDD_DDDD: Remaining amount of data in the ring buffer [byte]. You can see if the supply is stagnant.
WWWW ----: Write size to ring buffer [sector].
RRRR ----: Read size from ring buffer [byte].
FFFF ----: Frame number.
LLLL_LLLL: Delay time. (Current time-frame display time)
TTTT_TTTT: Frame time. (Frame display time + Frame display duration)
LFLF_LFLF: Frame drop counter.
SSSS_SSSS: Sample counter.
MODE ----: 0x80 ##: Stereo, 0x10 ##: 8bit, 0x ## 03: PCM stream playback number 3
             (In the case of PCM Stop, only the PCM stream playback number is displayed)
ADDR ----: PCM buffer start address (4bit right shift value)
SIZE ----: PCM buffer size [sample / 1ch]

▲ Back ｜ Forward ▼

★ MOVIE TOOLS GUIDE ★ Cinepak for SEGA Saturn