< 5/11>Cinepak for SEGASaturn User's Manual/4. Cinepak Library

★ MOVIE TOOLS GUIDE ★ Cinepak for SEGA Saturn

▲ Back ｜ Forward ▼

Cinepak for SEGASaturn/4． Cinepak Library

4.3 Programming considerations

Here are some things to keep in mind when playing movies using the Cinepak library.

(1) Precautions when creating applications

Please specify the WORK_RAM-H area (06000000H~) for the buffer address (CPK_PARA_WORK_ADDR, CPK_PARA_BUF_ADDR of CpkCreatePara) to be specified when creating a movie. Specifying a slow RAM area will reduce Cinepak's performance. The Cinepak library uses the CPU's DMA and timers. Do not use CPU DMA and timer when Cinepak is operating. If the same sound occurs twice, it is likely that CPK_Task is not called too many times or the image size is too large. Please call CPK_Task more often or reduce the image size.

(2) Relationship with other libraries

This library uses file system, stream system, and DMA library. Please 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 buffer you will need. Specifically, please ensure the minimum size of the movie file header + 0.5 seconds of sound + 80KB. Note that the larger the ring buffer, the faster Cinepak's processing will be.

"example"

1 minute movie, 44KHz, 16 bit, stereo at 30fps
Ring buffer size ≧ 32KB + 88KB + 80KB = 200KB

1 minute movie, 30fps, 11KHz, 8 bit, monaural
Ring buffer size ≧ 32KB + 5.5KB + 80KB = 117.5KB

The sound memory buffer size (CPK_PARA_PCM_SIZE of CpkCreatePara), which is a parameter when creating a movie, is the PCM quantization number for 1 channel.
Please specify an integer multiple of 4096. The range is 4096*4 to 4096*16.
For the buffer size, please specify a PCM quantization number 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 more.

(4) Chroma key processing

Chromakey processing slightly increases CPK_Task processing time. When using chromakey processing, set the transparent pixel invalid bit in the sprite command to 0. If you want to change the range of transparent colors during chromakey processing, change the range using the key out (transparent color) range setting function (CPK_SetKeyOutRange).

(5) Seamless branch

When seamless branching with CPK_EntryNext, the PCM volume and PAN will be the same as the previous movie. When seamless branching with CPK_EntryNext, you can play continuously for up to 60 minutes. Continuous playback is not possible beyond this point. Please start playing the movie once with CPK_Start. When seamless branching, please pre-read the movie file in the application program. If you use a file system, you cannot use seamless branching. Seamless branching can only be performed during playback of one movie. This cannot be executed while playing a multi-movie.

(6) Multi-movie playback

When playing multi-movies, set the PCM stream playback number to a different number. When playing multiple movies 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-movie. Please specify a different file. Multi-movie playback can be performed on up to four movies at the same time.

(7) Expanding the specified frame

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

(8) Function usage

Be sure to call CPK_Init at the beginning of your program. Be sure to call CPK_VblIn within the V blank IN interrupt. Please use CPK_GetTimeScale and CPK_GetHeader after reading the header part of the movie. CPK_Start can only be executed once for a movie handle. If you want to play the same movie file multiple times, please generate a movie handle each time. Please call CPK_SetDecodeAddr, CPK_SetColor, CPK_SetLoadNum, CPK_SetPcmCmdBlockNo, CPK_SetPcmStreamNo before playing the movie. After calling CPK_Task, be sure to check CPK_IsDispTime to see if the display timing is set. When CPK_IsDispTime returns TRUE, be sure to call CPK_CompleteDisp afterwards. For the movie handle generated with 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 be continued. In this case, delete the movie handle and close the file. After that, perform other processing such as playing the movie again.
Be sure to set each error processing function GFS_SetErrFunc, STM_SetErrFunc, CPK_SetErrFunc to detect errors. It also improves debugging efficiency.

(10) Precautions when using SCU-DMA

When data is transferred from the CD block to the ring buffer using SCU's DMA, peripheral information may not be obtained correctly.
In this case, it can be improved by setting the maximum number of transferred sectors (default value 20) to a smaller value, but if the setting is smaller, the task function must be called frequently enough to compensate.

[Processing example]

CPK_SetTrModeCd(cpk, CPK_TRMODE_SCU); /* Transfer using SCU-DMA */
CPK_SetLoadNum(cpk, 10); /* Maximum amount of transfer at one time [sector] */

Also, during SCU-DMA transfer, the bus used is occupied, so SH will be in a wait state from the moment you try to access the CPU bus. Please avoid using SCU-DMA as much as possible.

(11) Regarding changing the registration of the next handle

CPK_EntryNext is designed to cancel the previous registration by calling it again before switching. However, this cannot be canceled if processing of the next handle has already started internally just before switching.
Applications can determine this transition period from the replay status of the next handle.

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

		/* We are currently in the transition period to the next handle, so never */
		/* Do not call CPK_EntryNext. */

	} else {

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

	}
} 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 period to the next handle.

How to stay seamless during the transition period
In this situation, in order to switch seamlessly without freezing the screen, wait for the next handle to start playing, call CPK_EntryNext, then use CPK_CheckChange to make sure that enough data has been supplied, and switch using CPK_Change. .
How to force a switch during the transition period If seamlessness is not required, stop (erase) the currently playing handle and the next handle, and start playing the handle you want to play using CPK_Start or CPK_EntryNext and CPK_Change.

【Note】

The CinePack library cannot guarantee whether or not the switching will be seamless, as it is affected by the seek time to read the data of the next handle.
In the judgment processing example above, the statement ``Processing of the next handle has not started yet, so the registration of the next handle can be changed.'' does not mean that there is no problem when using the CinePack library. Therefore, this criterion may not be seamless.

To ensure complete seamlessness during registration changes, estimate the remaining playback time of the data stored in the currently active handle and ensure that you can seek and read in less time. If this is not possible, do not change the registration, wait until the handle is transferred, and switch using method ( 1. ).
Although it is difficult to make this judgment strictly, you can estimate the stockpiling amount using CPK_GetStockSize and CPK_GetStockTime, and you can be safe by assuming the worst seek and read times.

(12) Relationship between frame size and Cinepak compression method

Cinepak performs compression processing by dividing one frame into 1 to 3 parts depending on the frame size (area).
Before and after the splitting conditions, internal compression efficiency and image quality become discontinuous, and the following trends are thought to occur.

If it is smaller than the dividing condition and close to the dividing condition: poor image quality (compression rate is slightly better)
If it is larger than the dividing condition and close to the dividing condition: Good image quality (compression rate is slightly bad)

The exact dividing conditions are unknown, but the ranges we have confirmed are shown below.

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

* The CinePack library supports splitting into two or less.

(13) Efficiency of image decompression processing

Image decompression processing is more efficient to output to WORK RAM-H than directly to VRAM, so task functions operate faster this way.
If you output it to WORK RAM-H and then transfer it to VRAM using 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. Use this when you want to suppress the image size and frame rate and prioritize image quality.
It does not support 15-bit color movies; it supports 32,000-color display of 24-bit data, but you will be wasting high-quality data.
Convert an uncompressed QuickTime Movie with MovieToSaturn_J. There are no functions added for playing uncompressed movies. Since the file header is interpreted and processed, it can be played using exactly the same procedure. However, the ring buffer must be larger than when compressed.

ring buffer size

Ring buffers must be allocated to meet the following conditions:

ring ≧ header + sound + frame
ring: Ring buffer size header: File header size (rounded up to sector size boundary) sound : Size of 0.5 seconds of sound 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 Limit 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	Limit 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 processing of the Cinepack library.
If you experience malfunctions such as not being able to play smoothly, this will help you find the cause.
You can check whether tasks are being called regularly, whether data supply is delayed, and whether frames are being dropped.
It will be easier to analyze the history if you create a simpler execution history after checking the reproducibility of the malfunction.

[Internal processing of Cinepack 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 turned on/off, frame drop processing, PCM start/stop

[Output specification]

・When using the production program as is

Break after processing CPK_Init.
Check the address of the CpkdSys type structure cpkd_sys in the map file created during linking, and use the ICE command to set the value of cpkd_sys.mode to 0x00000001.

:m 060XXXXX 1;l

The output address will be 0x04000000 to 0x047fffff.

- When creating a program for debugging output, set CPKD_SetMode(ON) after CPK_Init.
CPKD_SetPrintAddr allows you to set the output address.
With CPKD_PrintStr and CPKD_PrintData, it is possible to add and output the execution history of the application side processing. When additionally outputting, please make the output size an integral multiple of 16 bytes to make the history information easier to read.

[Check output information]

Dump and display the output address using the ICE command. You can easily analyze the behavior by saving the displayed content as a text file and viewing it in a text editor.

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

[Format of output information]

========+============================================+
ADDRESS : 0 1  2 3   4 5  6 7   8 9  A B   C D  E F  :
========+============================================+
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. Know the approximate time.
EEEE_EEEE : Error code.
PPPP ---- : Playback status [-1, 0, 1, 2, 3, 4, 5].
HHHH_HHHH : Cinepack handle.
CCCC_CCCC : Cinepack task call counter.
DDDD_DDDD : Remaining amount of data in the ring buffer [byte]. Find out if there is a supply disruption.
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 : Dropped frame counter.
SSSS_SSSS : Sample counter.
MODE ---- : 0x80##:Stereo, 0x10##:8bit, 0x##03:PCM stream playback number 3
             (In 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