path: root/audio_codec/libcook/rv_decode_message.h (plain)
blob: 63d5e6eb6ef31d2cb358bfa608103680942147e2

1	/* ***** BEGIN LICENSE BLOCK *****
2	* Source last modified: $Id: rv_decode_message.h,v 1.1.1.1.2.1 2005/05/04 18:20:57 hubbe Exp $
3	*
4	* REALNETWORKS CONFIDENTIAL--NOT FOR DISTRIBUTION IN SOURCE CODE FORM
5	* Portions Copyright (c) 1995-2005 RealNetworks, Inc.
6	* All Rights Reserved.
7	*
8	* The contents of this file, and the files included with this file,
9	* are subject to the current version of the Real Format Source Code
10	* Porting and Optimization License, available at
11	* https://helixcommunity.org/2005/license/realformatsource (unless
12	* RealNetworks otherwise expressly agrees in writing that you are
13	* subject to a different license). You may also obtain the license
14	* terms directly from RealNetworks. You may not use this file except
15	* in compliance with the Real Format Source Code Porting and
16	* Optimization License. There are no redistribution rights for the
17	* source code of this file. Please see the Real Format Source Code
18	* Porting and Optimization License for the rights, obligations and
19	* limitations governing use of the contents of the file.
20	*
21	* RealNetworks is the developer of the Original Code and owns the
22	* copyrights in the portions it created.
23	*
24	* This file, and the files included with this file, is distributed and
25	* made available on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND,
26	* EITHER EXPRESS OR IMPLIED, AND REALNETWORKS HEREBY DISCLAIMS ALL
27	* SUCH WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF
28	* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT
29	* OR NON-INFRINGEMENT.
30	*
31	* Technology Compatibility Kit Test Suite(s) Location:
32	* https://rarvcode-tck.helixcommunity.org
33	*
34	* Contributor(s):
35	*
36	* ***** END LICENSE BLOCK ***** */
37
38	#ifndef RV_DECODE_MESSAGE_H
39	#define RV_DECODE_MESSAGE_H
40
41	#ifdef __cplusplus
42	extern "C" {
43	#endif /* #ifdef __cplusplus */
44
45	/* Define CPU scalability constants. Though these values range from */
46	/* 0 to 100, they are *not* intended to indicate a CPU utilization percentage. */
47
48	#define CPU_Scalability_Maximum 100
49	/* Maximum value for CPU usage setting: */
50	/* no shortcuts taken, best possible quality at the cost of higher */
51	/* CPU usage. This value is typically used for "off-line" compression. */
52
53	#define CPU_Scalability_Minimum 0
54	/* Minimum value for CPU usage setting: */
55	/* all implemented shortcuts taken, reduced CPU usage at the cost */
56	/* of reduced video quality. */
57
58	#define CPU_Scalability_Default 50
59	/* Default value for CPU usage setting: */
60	/* this represents the normal mode of operation and is equivalent */
61	/* to previously not choosing a CPU usage setting. */
62
63	#define RV89COMBO_MSG_ID_Decoder_CPU_Scalability 2002
64	/* Allows for the setting and getting of the decoders CPU scalability parameter */
65
66	/* */
67	/* Define formats for representing custom codec messages. */
68	/* Custom codec messages have semantics unknown to the HIVE/RV layer. */
69	/* The messages are defined by the underlying codec, and typically documented */
70	/* for use by applications. */
71	/* */
72
73	/* RV_Custom_Message_ID identifies a specific custom message. These */
74	/* identifiers are not guaranteed to be unique among different codecs. */
75	/* Thus an application using such messages, must have knowledge regarding */
76	/* which codec is being used, and what custom messages it supports. */
77	/* A codec will typically distribute a header file that defines its */
78	/* custom messages. */
79	/* */
80	/* Specific custom messages will be passed into a codec via a structure whose */
81	/* first member is a RV_Custom_Message_ID, and additional parameters */
82	/* understood by the application and the codec. The size of each such */
83	/* custom message structure is variable, depending on the specific message id. */
84	/* Messages that require no values other than a message id, can be indicated */
85	/* by using the RV_Custom_Message_ID as is. For such messages, there is no */
86	/* need to wrap the message id within another structure. */
87
88	typedef UINT32 RV_Custom_Message_ID;
89
90	/* RV_MSG_Simple is a structure used to pass custom messages which */
91	/* take one or two 32-bit values. The "message_id" member identifies a */
92	/* particular message, and the "value1" and "value2" members specify the */
93	/* 32-bit values. The interpretation of the values depends on the message id. */
94	/* They could be simple booleans (zero or non-zero), or arbitrary integers. */
95	/* Some messages will use only value1, and not value2. */
96
97	typedef struct {
98
99	RV_Custom_Message_ID message_id;
100
101	INT32 value1;
102	INT32 value2;
103
104	} RV_MSG_Simple;
105
106
107	/* The RV_MSG_DISABLE, RV_MSG_ENABLE and RV_MSG_GET values may be used as */
108	/* controls when manipulating boolean-valued custom messages. Typically, */
109	/* such messages will employ the RV_MSG_Simple structure. The message_id */
110	/* will identify a boolean-valued option being manipulated. The "value1" */
111	/* member will be set to one of RV_MSG_DISABLE, RV_MSG_ENABLE or RV_MSG_GET. */
112	/* Depending on the message id, "value2" may specify additional information */
113	/* such as a layer number for scalable video sequences. */
114	/* */
115	/* When value1 is RV_MSG_DISABLE or RV_MSG_ENABLE, the specified option */
116	/* will be disabled or enabled, respectively. */
117	/* When value1 is RV_MSG_GET, the current setting for the option (zero for */
118	/* disabled and non-zero for enabled) will be returned in "value2". */
119
120	#define RV_MSG_DISABLE 0
121	#define RV_MSG_ENABLE 1
122	#define RV_MSG_GET 2
123
124	/* The RV_MSG_SET control, along with RV_MSG_GET, provide an alternative */
125	/* way in which custom messages might use the RV_MSG_Simple structure. */
126	/* When value1 is RV_MSG_SET, value2 indicates the value which is being */
127	/* applied. The message_id provides the context to which value2 applies. */
128	/* Again, refer to the documentation describing each custom message to see */
129	/* if it uses RV_MSG_GET and RV_MSG_SET, or if it uses RV_MSG_DISABLE, */
130	/* RV_MSG_ENABLE and RV_MSG_GET. */
131
132	#define RV_MSG_SET 3
133
134
135
136
137
138	/* Decoder postfilters: */
139	/* - the smoothing postfilter is designed to remove general compression */
140	/* artifacts, mosquito noise, and ringing noise. */
141	/* - the annex J deblocking filter when used as a postfilter (annex J */
142	/* not encoded in bitstream), removes blocking artifacts (block */
143	/* edges) almost as efficiently as when used in-the-loop, i.e. encoded */
144	/* in bitstream. */
145	/* For the most video quality improvement, both filters should be used. */
146	/* However, each filter takes up a certain amount of CPU cycles, and */
147	/* for large formats, it may be too computationally expensive to use */
148	/* both. */
149	/* These filters are more effective, the lower the bitrate. */
150
151	/* */
152	/* Define a custom decoder message for enabling the smoothing postfilter. */
153	/* */
154	/* This message must be sent with the RV_MSG_Simple structure. */
155	/* Its value1 member should be RV_MSG_DISABLE, RV_MSG_ENABLE or RV_MSG_GET. */
156	/* Its value2 is only used for RV_MSG_GET, in which case it is used to */
157	/* return the current setting. */
158	/* */
159	#define RV_MSG_ID_Smoothing_Postfilter 17
160
161	/* Define a decoder message that helps the decoder determine when to display */
162	/* frames. */
163	/* */
164	/* The SNR, spatial and temporal scalability features of H.263+ Annex O */
165	/* have the property that frames are received at the decoder out of order, */
166	/* or that multiple frames (enhancement layers) are received at the decoder */
167	/* yet only one of these frames should be displayed. */
168	/* */
169	/* In the absence of apriori knowledge regarding the video sequence it is */
170	/* going to receive, an H.263+ decoder might not know when it is okay to */
171	/* go ahead and display a picture it has just decoded. */
172	/* */
173	/* To help solve this problem, the ILVC decoder can operate in two modes. */
174	/* The first and default mode is termed "no latency". In this scenario, */
175	/* the decoder assumes it will not be receiving B frames nor enhancement */
176	/* layers. The decoder will decode and display the very first frame it sees. */
177	/* If the decoder encounters any B frames or enhancement layers, it then */
178	/* goes into latency mode (described below). When B frames or enhancement */
179	/* layers are present under latency mode, some of these frame types will */
180	/* not be displayed by the decoder at the beginning of a video sequence. */
181	/* This is because the decoder either already displayed a frame for the */
182	/* same temporal reference point, or because the decoder no longer has */
183	/* the appropriate reference frames from which to decode a B frame. */
184	/* */
185	/* Under latency mode, the decoder will generally not display a decoded frame, */
186	/* until it has detected that no enhancement layer frames or dependent */
187	/* B frames will be coming. This detection usually occurs when a subsequent */
188	/* non-B frame is encountered. This mode has the advantage that no frames */
189	/* will be dropped at the beginning of a sequence. The disadvantage is that */
190	/* a latency of one or more temporal references is introduced before a frame */
191	/* is displayed. */
192	/* */
193	/* This message must be sent with the RV_MSG_Simple structure. */
194	/* Its value1 member should be RV_MSG_DISABLE, RV_MSG_ENABLE or RV_MSG_GET. */
195	/* For RV_MSG_GET, the current setting is returned in value2. */
196
197	#define RV_MSG_ID_Latency_Display_Mode 21
198
199
200
201	/* */
202	/* Define a custom decoder message that enables/disables the error */
203	/* concealment in the decoder. */
204	/* */
205	/* This message must be sent with the RV_MSG_Simple structure. */
206	/* Its value1 member should be RV_MSG_DISABLE, RV_MSG_ENABLE or RV_MSG_GET. */
207	/* Its value2 is only used for RV_MSG_GET, in which case it is used to */
208	/* return the current setting. */
209	/* */
210	#define RV_MSG_ID_Error_Concealment 23
211
212
213	/* #define RV_MSG_ID_* = 24; */
214	/* // Obsolete, do not use 24. */
215	/* #define RV_MSG_ID_* = 25; */
216	/* // Obsolete, do not use 25. */
217
218	/* */
219	/* Define a custom decoder message to be used when decoding a non-compliant */
220	/* H.263+ bitstream, that informs the decoder about information which is */
221	/* normally gleaned from parsing the picture header. In this scenario, the */
222	/* encoder is generating a bitstream having a lean and mean picture header. */
223	/* The invariant picture header contents are sent over the wire only once, */
224	/* prior to streaming any bitstreams. */
225	/* */
226	#define RV_MSG_ID_Set_Picture_Header_Invariants 26
227	/* */
228	/* This message must be sent with the RV_MSG_Simple structure. */
229	/* Its value1 member is interpreted as a bit mask, described below. */
230	/* Its value2 member is not used. */
231	/* */
232	/* The following bits should be set or cleared, as appropriate, to indicate */
233	/* which codec options will be enabled or disabled for the video sequence. */
234	/* If any of these change, then the changes should be communicated to the */
235	/* decoder via this custom message prior to it seeing any input frames */
236	/* having the new state. */
237	/* */
238
239
240	#define RV_MSG_SPHI_Slice_Structured_Mode 0x20
241
242
243	/* */
244	/* Define messages that are used with the RealVideo bitstream, */
245	/* to communicate the locations of slice boundaries between the front-end */
246	/* codec and the back-end encoder or decoder. */
247	/* */
248
249	typedef struct {
250	UINT32 is_valid;
251	UINT32 offset;
252	} RV_Segment_Info;
253	/* The RV_Segment_Info structure *MUST* be structurally equivalent */
254	/* to the PNCODEC_SEGMENTINFO structure defined in the RealVideo */
255	/* front-end. Typically an array of these structures is allocated, */
256	/* with each element describing one slice in a compressed bit stream. */
257	/* For the output of an encoder, is_valid is always true. 'offset' */
258	/* indicates the offset of a slice within an associated bitstream. */
259	/* The first slice is at offset 0. */
260
261	typedef struct {
262	RV_Custom_Message_ID message_id;
263	/* message_id must be RV_MSG_ID_Get_Encode_Segment_Info */
264	/* or RV_MSG_ID_Set_Decode_Segment_Info. */
265
266	UINT32 number_of_segments;
267
268	RV_Segment_Info *segment_info;
269	} RV_Segment_Info_MSG;
270
271
272	#define RV_MSG_ID_Set_Decode_Segment_Info 28
273	/* This message, sent with the RV_Segment_Info_MSG structure, is used */
274	/* to specify slice information to the decoder just prior to decoding */
275	/* a bitstream. */
276	/* number_of_segments should be set to one less than the number of */
277	/* slices in the frame about to be decoded. */
278	/* segment_info should point to an array of RV_Segment_Info */
279	/* structures, which point to the slice offsets of the bitstream */
280	/* that will be decoded next. */
281
282
283
284	/* */
285	/* Define a custom decoder message for setting the smoothing postfilter's */
286	/* strength. The strength ranges from 0 to RV_Maximum_Smoothing_Strength, */
287	/* inclusive. */
288	/* */
289	/* This message must be sent with the RV_MSG_Simple structure. */
290	/* Its value1 member should be RV_MSG_SET or RV_MSG_GET. */
291	/* For RV_MSG_SET, value2 should be assigned the desired strength setting. */
292	/* For RV_MSG_GET, value2 is assigned upon return to the current strength */
293	/* setting. */
294	/* */
295	#define RV_MSG_ID_Smoothing_Strength 30
296
297	#define RV_Maximum_Smoothing_Strength 3
298	#define RV_Default_Smoothing_Strength 1
299
300
301
302	/* Define a message to set the number of sizes, as well as the list of sizes */
303	/* that are to be used for RealVideo-style RPR */
304	/* This information is transmitted in the SPO (once). The front-end uses */
305	/* the RV_MSG_ID_Set_RVDecoder_RPR_Data to communicate this information */
306	/* to the back-end. Then, if num_sizes != 0, the back-end will read the */
307	/* following information from the slice header: */
308	/* .. */
309	/* [TR (as before)] */
310	/* if num_sizes != 0 */
311	/* PCTSZ = getbits(log2(num_sizes)) */
312	/* [MBA (as before)] */
313	/* .. */
314
315
316	#define RV_MSG_ID_Set_RVDecoder_RPR_Sizes 36
317
318	typedef struct {
319
320	RV_Custom_Message_ID message_id;
321	/* message_id must be RV_MSG_ID_Set_RVDecoder_RPR_Sizes. */
322
323	UINT32 num_sizes;
324	/* The number of sizes to be used (switched between). */
325	/* This number should include the original image size. */
326	/* The maximum number of sizes is currently limited to 8. */
327
328
329	UINT32 *sizes;
330	/* Pointer to array of image sizes. The array should have the */
331	/* following format: */
332	/* for (i = 0; i < num_sizes; i++) { */
333	/* UINT32 horizontal_size[i] */
334	/* UINT32 vertical_size[i] */
335	/* } */
336	/* This array should include the original image size */
337	/* The order of sizes is not important. The decoder will */
338	/* use PCTSZ as an index to look up in the array: */
339	/* new_width = horizontal_size[PCTSZ] */
340	/* new_height = vertical_size[PCTSZ] */
341
342	} RV_MSG_RVDecoder_RPR_Sizes;
343
344
345
346
347	/* Define a custom message to obtain timings for parts of the decode */
348	/* For now, only the smoothing filte is interesting. */
349	/* More could be added later */
350
351	#define RV_MSG_ID_Get_Decoder_Timings 42
352	typedef struct {
353
354	RV_Custom_Message_ID message_id;
355
356	double smoothing_time;
357	double fru_time;
358	} RV_MSG_Get_Decoder_Timings;
359
360
361	/* */
362	/* Define a custom message to set the video surface hardware */
363	/* allocator and its properties */
364
365	#define RV_MSG_ID_Hw_Video_Memory 43
366	/* */
367	/* This message must be sent with the RV_MSG_Simple structure. */
368	/* Its value1 member should be RV_MSG_DISABLE, RV_MSG_ENABLE or RV_MSG_GET. */
369	/* For RV_MSG_GET, the current number of frame buffers is returned in value2, */
370	/* and RV_MSG_ENABLE or RV_MSG_DISABLE returned in value1 */
371
372
373	/* */
374	/* Define a custom message to perform postfiltering into video */
375	/* memory */
376	/* */
377	#define RV_MSG_ID_PostfilterFrame 44
378	typedef struct {
379
380	RV_Custom_Message_ID message_id;
381	UINT8 * data;
382	UINT8 * dest_buffer;
383	UINT32 dest_pitch;
384	INT32 cid_dest_color_format;
385	UINT32 flags;
386	} RV_MSG_PostfilterFrame;
387
388
389
390	/* */
391	/* Define a custom message to release frame from video */
392	/* memory. */
393	/* 'data' is a pointer to a DecodedFrame structure */
394	/* */
395
396	#define RV_MSG_ID_ReleaseFrame 45
397	typedef struct {
398
399	RV_Custom_Message_ID message_id;
400	UINT8 * data;
401	} RV_MSG_ReleaseFrame;
402
403
404	/* */
405	/* Define a custom message to retrieve latest DecodedFrame data */
406	/* */
407	#define RV_MSG_ID_RetrieveFrame 46
408	typedef struct {
409
410	RV_Custom_Message_ID message_id;
411	void * frame;
412	} RV_MSG_RetrieveFrame;
413
414
415	/* */
416	/* Define a custom message to set the relied callback function */
417	/* that is the function to be called in the renderer in case */
418	/* it needs to blit (flip) a frame */
419	/* */
420
421	#define RV_MSG_ID_SetReliefCallback 48
422	typedef struct {
423
424	RV_Custom_Message_ID message_id;
425	void * cmtm;
426	/* pointer to PN_CMTM struct (pncodec.h) */
427	} RV_MSG_SetReliefCallback;
428
429	/* */
430	/* Define a custom message that enables/disables FRU */
431	/* */
432	#define RV_MSG_ID_Frame_Rate_Upsampling 49
433
434
435
436	/* */
437	/* Define a custom message to get CPU performance counters from the decoder. */
438	/* */
439	#define RV_MSG_ID_Get_Decoder_Performance_Counters 52
440
441	typedef struct {
442	RV_Custom_Message_ID message_id;
443	UINT32 uNumCounters;
444	UINT32 *pCounters;
445	} RV_MSG_Get_Decoder_Performance_Counters;
446
447
448	/* */
449	/* Define a custom message to enable and disable multithreading in the decoder */
450	/* */
451	#define RV_MSG_ID_Decoder_Multi_Threading 54
452
453	/* */
454	/* Define a custom message to enable decoding of beta streams with multiple threads */
455	/* */
456	#define RV_MSG_ID_Decoder_Beta_Stream 55
457
458	/* */
459	/* Define a custom message to signal RV8 bitstream */
460	/* */
461	#define RV_MSG_ID_RealVideo8 56
462
463	/* */
464	/* Define a custom message to retrieve latest DecodedFrame data */
465	/* */
466	#define RV_MSG_ID_RetrieveFrameData 57
467	typedef struct {
468
469	RV_Custom_Message_ID message_id;
470	void * m_data;
471	UINT8 * m_pYPlane;
472	UINT8 * m_pUPlane;
473	UINT8 * m_pVPlane;
474	UINT32 m_pitch;
475	UINT32 m_width;
476	UINT32 m_height;
477	} RV_MSG_RetrieveFrameData;
478
479
480
481	/* */
482	/* Note to developers: */
483	/* */
484	/* Next available message ID is 58. */
485	/* But 100 and above might already be in use, in "ccustmsg.h", so be careful. */
486	/* */
487
488	#ifdef __cplusplus
489	}
490	#endif
491
492	#endif /* RV_DECODE_MESSAGE_H */
493