MJPEG PC Decoding Library Software API Reference
MJPEG PC Decoding Library Software API Reference
API Reference
Issue 01
Date 2008-11-30
BOM N/A
Copyright © Shenzhen Hisilicon Semiconductor Co., Ltd. 2008. All rights reserved.
No part of this document may be reproduced or transmitted in any form or by any means without prior
written consent of Shenzhen Hisilicon Semiconductor Co., Ltd.
Notice
The information in this document is subject to change without notice. Every effort has been made in the
preparation of this document to ensure accuracy of the contents, but all statements, information, and
recommendations in this document do not constitute the warranty of any kind, express or implied.
Contents
2 API Functions..............................................................................................................................2-1
2.1 HiMJPEGDecCreate ...................................................................................................................................2-2
2.2 HiMJPEGDecDestroy .................................................................................................................................2-3
2.3 HiMJPEGDecGetInfo .................................................................................................................................2-4
2.4 HiMJPEGDecFrame....................................................................................................................................2-7
4 Application Instances................................................................................................................4-1
4.1 Working Flow of the M-JPEG Decoding ....................................................................................................4-2
4.2 Application Instances...................................................................................................................................4-2
Figures
Tables
Purpose
This section describes the document contents, related product version, intended audience,
conventions and update history.
This document describes the API function types of the the MJPEG PC decoding library and
their relations, describes all the reference information in details, and then describes how to use
the APIs of the MJPEG PC decoding library through instances.
Related Versions
The following table lists the product versions related to this document.
Intended Audience
The document describes types of reference information related to the HiSilicon H.264 PC
decoding library. Therefore, this document is intended for the programmers who meet the
following requirements:
z Be familiar with C/C++ programming language
z Be familiar with 32-bit Windows environment
Organization
This document is organized as follows:
Chapter Description
Conventions
Symbol Conventions
The following symbols may be found in this document. They are defined as follows.
Symbol Description
General Conventions
Convention Description
Convention Description
Table Contents
Content Description
- Not applicable
* A wild card
Update History
Updates between document versions are cumulative. Therefore, the latest document version
contains all updates made to previous versions.
1 Overview
Section Describes
1.1 Introduction
The M-JPEG PC decoding library provided by HiSilicon Technologies Co., Ltd. is a set of
decoding software with high performance, reliability, and compatibility. The decoding library
implements the M-JPEG decoding process internally and provides flexible APIs for users to
develop applications quickly.
In Windows, the decoding library provides a dynamic link library and a static link library for
calling API functions. This helps users easier develop applications. Table 1-1 lists the key
software development kit (SDK) components of the decoding library.
Static link hi_mjpeg_dec_w.lib When using the static link library, ignore the
library following four library files in the compiler option
group: libm.lib, libguide.lib, libirc.lib, and
svml_disp.lib. Otherwise, an alarm indicating an
failed link is displayed during the compiling
process.
Dynamic link hi_mjpeg_dec_w.lib –
library hi_mjpeg_dec_w.dll
Demo code hi_mjpeg_sample.c Demonstrate how to call the decoding library
APIs by taking decoding a local stream file as an
example.
Users can develop applications based on the decoding library in multiple compiling
environments. The decoding library is compatible with the Windows 2000 or the mainstream
Windows operating systems of the later versions. The decoding library is also compatible with
most PC-oriented CPU chipsets provided by Intel or AMD since 2002. Table 1-2 lists the
major development and running environments for the decoding library.
Field Function
Field Function
Request Lists the required header files and library files when an API is called.
Note Lists the precautions when an API is called.
2 API Functions
Section Describes
2.1 HiMJPEGDecCreate
[Purpose]
Create and initialize a handle for a decoder.
[Syntax]
HI_HANDLE HiMJPEGDecCreate( MJPEG_DEC_ATTR_S *pDecAttr );
[Description]
Before decoding, the function performs the following operations:
z Allocate the decoding memory.
z Initialize the decoder-related variables and states.
z Set the attributes of the decoder, such as the maximum width and height of a picture.
To support multi-channel decoding, the upper-layer applications use multiple threads to create
multiple decoders.
[Parameter]
[Return Value]
[Request]
z Header files: hi_config.h and hi_mjpeg_api.h.
z Library file: hi_mjpeg_dec_w.lib.
[Note]
None.
2.2 HiMJPEGDecDestroy
[Purpose]
Destroy a decoder.
[Syntax]
void HI_HiMJPEGDecDestroy( HI_HANDLE hDec );
[Description]
Destroy the decoder to release the allocated memory. When the decoding is finished, this
function can be called to avoid the memory leakage.
[Parameter]
[Return Value]
None.
[Request]
z Header files: hi_config.h and hi_mjpeg_api.h.
z Library file: hi_mjpeg_dec_w.lib.
[Note]
The destroyed handle must be set to NULL manually.
2.3 HiMJPEGDecGetInfo
[Purpose]
Query the version information of the decoding library and the function set of the current
version.
[Syntax]
HI_S32 HiMJPEGDecGetInfo( MJPEG_LIBINFO_S *pLibInfo );
[Description]
Before creating a decoder, users can call this function to query the version information and
function set of the decoding library.
[Parameter]
[Return Value]
[Request]
z Header files: hi_config.h and hi_mjpeg_api.h.
z Library file: hi_mjpeg_dec_w.lib.
[Note]
None.
2.4 HiMJPEGDecFrame
[Purpose]
Decode the input stream containing only one JPEG frame and output this frame.
[Syntax]
HI_S32 HiMJPEGDecFrame(
HI_HANDLE hDec,
HI_U8 *pStream,
HI_U32 iStreamLen,
HI_U64 ullPTS,
MJPEG_DEC_FRAME_S *pDecFrame,
HI_U32 uFlags
);
[Description]
Each time the HiMJPEGDecFrame function is called, the configured stream should contain
one JPEG picture only. In addtion, the frame is output immediately by the decoder.
The HiMJPEGDecFrame provides the time stamp transparent transmission function. The
input time stamp is saved in the current decoded picture structure MJPEG_DEC_FRAME_S
and is output with the decoded picture. For details, see section 3.2.4
"MJPEG_DEC_FRAME_S."
[Parameter]
[Return Value]
[Request]
z Header files: hi_config.h and hi_mjpeg_api.h.
z Library file: hi_mjpeg_dec_w.lib.
[Note]
The decoding library only allows that the JPEG pictures are decoded by frame. Therefore, the
input stream must only contain one JPEG frame when the 2.4 HiMJPEGDecFrame is called.
If the input stream cannot form a frame, only a part of the picture is output. If the input stream
forms multiple frames, only the first frame is decoded and output.
Section Describes
[Note]
None.
3.2.2 MJPEG_LIBINFO_S
[Description]
Data structure of the version, copyright, and function set information of the decoding library.
[Definition]
*/
HI_U32 uPicHeight; /* Maximum picture height (in the unit of pixel)
*/
HI_U32 uReserved; /* Reserved */
} MJPEG_LIBINFO_S;
[Note]
None.
3.2.3 MJPEG_DEC_ATTR_S
[Description]
Data structure of the decoder attribute information.
[Definition]
/* Data structure of the decoder attribute information */
typedef struct hiMJPEG_DEC_ATTR_S
{
HI_U32 uPictureFormat; /* Reserved */
HI_U32 uStreamInType; /* Reserved */
HI_U32 uPicWidth; /* Maximum picture width (in the unit of
pixel) */
HI_U32 uPicHeight; /* Maximum picture height (in the unit of
pixel) */
HI_U32 uWorkMode; /* Reserved */
MJPEG_USERDATA_S *pUserData; /* User data */
HI_U32 uReserved; /* Reserved */
} MJPEG_DEC_ATTR_S;
[Note]
None.
3.2.4 MJPEG_DEC_FRAME_S
[Description]
Data structure of the output picture information of the decoder.
[Definition]
/* Data structure of the output picture information of the decoder */
typedef struct hiMJPEG_DEC_FRAME_S
{
HI_U8 *pY; /* Pixel Y pointer */
HI_U8 *pU; /* Pixel U pointer */
HI_U8 *pV; /* Pixel V pointer */
HI_U32 uYStride; /* Luminance stride (in the unit of pixel)
*/
[Note]
None.
4 Application Instances
Section Describes
4.1 Working Flow of the The working flow of the M-JPEG decoding.
M-JPEG Decoding
4.2 Application Instances The API application instances.
Start
Create a decoder
A frame of JPEG
stream
Decoding
No
Sequence ends?
Yes
End
/* Allocate memory for the stream buffer area. The allocated memory must be
greater than the size of a frame of picture */
bitstream = malloc(BUFF_LEN);
/* Create a decoder */
dec_attrbute.uPicWidth = WIDTH; /* Maximum picture width (in the unit of
pixel) */
dec_attrbute.uPicHeight = HEIGHT; /* Maximum picture height (in the unit
of pixel) */
handle = HiMJPEGDecCreate(&dec_attrbute);
/* Open the JPEG stream file and the file used to store the YUV picture */
jpeg = fopen(argv[1], "rb");
yuv = fopen(argv[2], "wb");
if(NULL == jpeg || NULL == yuv || NULL == bitstream || NULL == handle)
{
goto END;
}
/* Read a frame of JPEG stream data from the JPEG stream file */
len = fread(bitstream, 1, BUFF_LEN, jpeg);
/* Decoding process:
Return HI_JPEG_DEC_OK : The decoding is successful and a picture is
output;
Return HI_JPEG_NO_PICTURE : The decoding fails and no picture is output;
Return HI_JPEG_ERR_HANDLE : The input parameters are incorrect.
*/
result = HiMJPEGDecFrame(handle, bitstream, len, 0, &dec_frame, 0);
switch(dec_frame.uPictureFormat )
{
case 0: /* YUV420 */
cHeight = (yHeight + 1) / 2;
break;
case 1: /* YUV422 */
cHeight = yHeight;
break;
case 2: /* YUV444 */
cHeight = yHeight;
break;
case 3: /* YUV422 (MCU 1x2) */
cHeight = (yHeight + 1) / 2;
break;
default: /* YUV400 */
cHeight = 0;
break;
}
/* If the decoding is successful, the information about the picture format,
picture width, and picture height can be obtained, and a picture is output
or displayed */
printf("picture format: %s. width: %d, height: %d.\n",
PictureFormatString[dec_frame.uPictureFormat], dec_frame.uWidth,
dec_frame.uHeight);
fwrite(dec_frame.pY, 1, yStride * yHeight, yuv);
fwrite(dec_frame.pU, 1, cStride * cHeight, yuv);
fwrite(dec_frame.pV, 1, cStride * cHeight, yuv);
}
END:
/* Release the stream buffer area */
if(NULL != bitstream)
free(bitstream);
/* Close the input JPEG stream file and output the YUV picture */
if(NULL != jpeg)
fclose(jpeg);
if(NULL != yuv)
fclose(yuv);
if(NULL != handle)
HiMJPEGDecDestroy(handle);
handle = NULL;