fw-encoder-api.txt

V4l driver for DVB HD

Encoder firmware API description
================================

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_PING_FW
Enum 	128/0x80
Description
	Does nothing. Can be used to check if the firmware is responding.

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_START_CAPTURE
Enum 	129/0x81
Description
	Commences the capture of video, audio and/or VBI data. All encoding
	parameters must be initialized prior to this API call. Captures frames
	continuously or until a predefined number of frames have been captured.
Param[0]
	Capture stream type:
	    0=MPEG
	    1=Raw
	    2=Raw passthrough
	    3=VBI

Param[1]
	Bitmask:
	    Bit 0 when set, captures YUV
	    Bit 1 when set, captures PCM audio
	    Bit 2 when set, captures VBI (same as param[0]=3)
	    Bit 3 when set, the capture destination is the decoder
		(same as param[0]=2)
	    Bit 4 when set, the capture destination is the host
	Note: this parameter is only meaningful for RAW capture type.

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_STOP_CAPTURE
Enum 	130/0x82
Description
	Ends a capture in progress
Param[0]
	0=stop at end of GOP (generates IRQ)
	1=stop immediate (no IRQ)
Param[1]
	Stream type to stop, see param[0] of API 0x81
Param[2]
	Subtype, see param[1] of API 0x81

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_AUDIO_ID
Enum 	137/0x89
Description
	Assigns the transport stream ID of the encoded audio stream
Param[0]
	Audio Stream ID

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_VIDEO_ID
Enum 	139/0x8B
Description
	Set video transport stream ID
Param[0]
	Video stream ID

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_PCR_ID
Enum 	141/0x8D
Description
	Assigns the transport stream ID for PCR packets
Param[0]
	PCR Stream ID

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_FRAME_RATE
Enum 	143/0x8F
Description
	Set video frames per second. Change occurs at start of new GOP.
Param[0]
	0=30fps
	1=25fps

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_FRAME_SIZE
Enum 	145/0x91
Description
	Select video stream encoding resolution.
Param[0]
	Height in lines. Default 480
Param[1]
	Width in pixels. Default 720

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_BIT_RATE
Enum 	149/0x95
Description
	Assign average video stream bitrate.
Param[0]
	0=variable bitrate, 1=constant bitrate
Param[1]
	bitrate in bits per second
Param[2]
	peak bitrate in bits per second, divided by 400

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_GOP_PROPERTIES
Enum 	151/0x97
Description
	Setup the GOP structure
Param[0]
	GOP size
Param[1]
	Number of B frames between the I and P frame, plus 1.
	For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_ASPECT_RATIO
Enum 	153/0x99
Description
	Sets the encoding aspect ratio. Changes in the aspect ratio take effect
	at the start of the next GOP.
Param[0]
	'0000' forbidden
	'0001' 1:1 square
	'0010' 4:3
	'0011' 16:9
	'0100' 2.21:1
	'0101' reserved
	 ....
	'1111' reserved

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_DNR_FILTER_MODE
Enum 	155/0x9B
Description
	Assign Dynamic Noise Reduction operating mode
Param[0]
	Bit0: Spatial filter, set=auto, clear=manual
	Bit1: Temporal filter, set=auto, clear=manual
Param[1]
	Median filter:
	    0=Disabled
	    1=Horizontal
	    2=Vertical
	    3=Horiz/Vert
	    4=Diagonal

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_DNR_FILTER_PROPS
Enum 	157/0x9D
Description
	These Dynamic Noise Reduction filter values are only meaningful when
	the respective filter is set to "manual" (See API 0x9B)
Param[0]
	Spatial filter: default 0, range 0:15
Param[1]
	Temporal filter: default 0, range 0:31

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_CORING_LEVELS
Enum 	159/0x9F
Description
	Assign Dynamic Noise Reduction median filter properties.
Param[0]
	Threshold above which the luminance median filter is enabled.
	Default: 0, range 0:255
Param[1]
	Threshold below which the luminance median filter is enabled.
	Default: 255, range 0:255
Param[2]
	Threshold above which the chrominance median filter is enabled.
	Default: 0, range 0:255
Param[3]
	Threshold below which the chrominance median filter is enabled.
	Default: 255, range 0:255

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
Enum 	161/0xA1
Description
	Assign spatial prefilter parameters
Param[0]
	Luminance filter
	    0=Off
	    1=1D Horizontal
	    2=1D Vertical
	    3=2D H/V Separable (default)
	    4=2D Symmetric non-separable
Param[1]
	Chrominance filter
	    0=Off
	    1=1D Horizontal (default)

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_3_2_PULLDOWN
Enum 	177/0xB1
Description
	3:2 pulldown properties
Param[0]
	0=enabled
	1=disabled

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_VBI_LINE
Enum 	183/0xB7
Description
	Selects VBI line number.
Param[0]
	Bits 0:4 	line number
	Bit  31		0=top_field, 1=bottom_field
	Bits 0:31 	all set specifies "all lines"
Param[1]
	VBI line information features: 0=disabled, 1=enabled
Param[2]
	Slicing: 0=None, 1=Closed Caption
	Almost certainly not implemented. Set to 0.
Param[3]
	Luminance samples in this line.
	Almost certainly not implemented. Set to 0.
Param[4]
	Chrominance samples in this line
	Almost certainly not implemented. Set to 0.

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_STREAM_TYPE
Enum 	185/0xB9
Description
	Assign stream type
Param[0]
	 0=Program stream
	 1=Transport stream
	 2=MPEG1 stream
	 3=PES A/V stream
	 5=PES Video stream
	 7=PES Audio stream
	10=DVD stream
	11=VCD stream
	12=SVCD stream
	13=DVD_S1 stream
	14=DVD_S2 stream

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_OUTPUT_PORT
Enum 	187/0xBB
Description
	Assign stream output port (not recommended you change setting from default)
Param[0]
	0=Memory (default)
	1=Streaming
	2=Serial

-------------------------------------------------------------------------------

Name 	CX2341X_ENC_SET_AUDIO_PROPERTIES
Enum 	189/0xBD
Description
	Set audio stream properties, may be called while encoding is in progress.
	Note: all bitfields are consistent with ISO11172 documentation except
	bits 2:3 which ISO docs define as:
		'11' Layer I
		'10' Layer II
		'01' Layer III
		'00' Undefined
	This discrepancy may indicate a possible error in the documentation.
Param[0]
	Bitmask:
	   0:1  '00' 44.1Khz
	    	'01' 48Khz
	    	'10' 32Khz
	    	'11' reserved

	   2:3  '01'=Layer I
		'10'=Layer II

	   4:7  Bitrate:
	    	     Index | Layer I     | Layer II
	    	     ------+-------------+------------
	    	    '0000' | free format | free format
	    	    '0001' |  32 kbit/s  |  32 kbit/s
	    	    '0010' |  64 kbit/s  |  48 kbit/s
	    	    '0011' |  96 kbit/s  |  56 kbit/s
	    	    '0100' | 128 kbit/s  |  64 kbit/s
	    	    '0101' | 160 kbit/s  |  80 kbit/s
	    	    '0110' | 192 kbit/s  |  96 kbit/s
	    	    '0111' | 224 kbit/s  | 112 kbit/s
	    	    '1000' | 256 kbit/s  | 128 kbit/s
	    	    '1001' | 288 kbit/s  | 160 kbit/s
	    	    '1010' | 320 kbit/s  | 192 kbit/s
	    	    '1011' | 352 kbit/s  | 224 kbit/s
	    	    '1100' | 384 kbit/s  | 256 kbit/s
	    	    '1101' | 416 kbit/s  | 320 kbit/s
	    	    '1110' | 448 kbit/s  | 384 kbit/s
	    	Note: For Layer II, not all combinations of total bitrate
	    	and mode are allowed. See ISO11172-3 3-Annex B, Table 3-B.2

	   8:9  '00'=Stereo
	    	'01'=JointStereo
	    	'10'=Dual
	    	'11'=Mono

	  10:11 Mode Extension used in joint_stereo mode.
	    	In Layer I and II they indicate which subbands are in
		intensity_stereo. All other subbands are coded in stereo.
	    	    '00' subbands 4-31 in intensity_stereo, bound==4
	    	    '01' subbands 8-31 in intensity_stereo, bound==8
	    	    '10' subbands 12-31 in intensity_stereo, bound==12
	    	    '11' subbands 16-31 in intensity_stereo, bound==16

	  12:13 Emphasis:
	    	    '00' None
	    	    '01' 50/15uS
	    	    '10' reserved
	    	    '11' CCITT J.17

	  14 	CRC:
	    	    '0' off
	    	    '1' on

	  15    Copyright:
	    	    '0' off
	    	    '1' on