include/mm.h

   1 /*
   2  * libmm-common
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jonghyuk Choi <jhchoi.choi@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22
  23 #ifndef __MM_H__
  24 #define __MM_H__
  25
  26 #include <stdbool.h>
  27
  28 #include <mm_types.h>
  29 #include <mm_error.h>
  30 #include <mm_message.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37         @addtogroup COMMON
  38         @{
  39          * @file                mm.h
  40          * @author
  41          * @version             1.0
  42          * @brief               This file includes all the necessary header files of multimediaframework.
  43
  44         @mainpage Multimedia Framework
  45
  46         @par
  47         This document provides necessary information for developers who are going
  48         to implement multimedia application such as media player, voice recorder,
  49         and camera application and so on. Before entering into the detailed
  50         information, this also has described the overview, architecture design and
  51         each component of multimedia framework for the purpose of helping
  52         developers to understand concept or basic knowledge in relation to API for
  53         themselves.
  54
  55         @par
  56         Here is outline as below.
  57
  58         @par
  59         - @ref OVERVIEW
  60         - @ref ARCHITECTURE
  61         - @ref COMPONENT
  62         - @ref CONCEPT
  63
  64         @section OVERVIEW       Overview
  65
  66         @par
  67         Multimedia Framework is designed to provide easy to use services for
  68         developing multimedia applications based on an embedded Linux platform.
  69
  70         @par
  71         Multimedia framework API reference has defined APIs to support functions
  72         as below;
  73
  74         @par
  75         - Playback of multimedia contents.
  76         - Playing system sounds.
  77         - Controlling volume information.
  78         - Controlling direction of sound input / output path.
  79         - Recording video stream from video input device such as camera
  80         - Recording audio stream from audio input device such as microphone
  81         - Capturing still image from video input device
  82         - Extract meta data information from file
  83
  84         @par
  85         This document will describe architecture of multimedia framework, basic
  86         concept of design of application programming, and explain how to use this
  87         framework
  88
  89         @section ARCHITECTURE   Architecture Design
  90
  91         @par
  92         The multimedia framework can be divided into three parts as follows;
  93
  94         @par
  95         - Application Layer that provide high-level APIs to multimedia applications.
  96         - Internal Layer of Multimedia Framework.
  97         - Hardware/Platform Dependent Layer.
  98
  99         @par
 100         Libraries which provide high-level APIs can be divided into five components
 101         again; Player, Sound, File, Image, and Camcorder. Basically each component
 102         can be loaded to memory independently to decrease memory foot print.
 103
 104         @par
 105         The internal library is a library which is responsible for encoding /
 106         decoding multimedia stream. Application layer library uses this library
 107         for playback, or recording.
 108
 109         @par
 110         Hardware / Platform dependent layer has dependency on hardware or platform.
 111         If hardware or platform has been changed, this layer library must be ported
 112         to that environment. So this can be called as Porting Layer.
 113
 114         @par
 115         This architecture diagram below is a high-level diagram of multimedia
 116         framework and then also shows how multimedia framework works as well as its
 117         components.
 118
 119         @image html             architecture.png "Architecture Diagram" width=12cm
 120         @image latex    architecture.png "Architecture Diagram" width=12cm
 121
 122         @par
 123         Each components will be describes in more detail on Component Description
 124         section.
 125
 126         @section COMPONENT      Component Description
 127
 128         @par
 129         As mentioned previous section, Multimedia Framework can be divided into
 130         3 layers. Components for each layer of Multimedia Framework are as below;
 131
 132         @par
 133         Application Export Layer
 134
 135         @par
 136         - @ref MMFW ATTRS LIBRARY
 137         - @ref MMFW PLAYER LIBRARY
 138         - @ref MMFW CAMCORDER LIBRARY
 139         - @ref MMFW SOUND LIBRARY
 140         - @ref MMFW FILE LIBRARY
 141
 142         @par
 143         Internal (Not exported) Layer
 144
 145         @par
 146         - Multimedia Codec (Encoder / Decoder)
 147
 148         @par
 149         Hardware/Platform Dependent Layer
 150
 151         @par
 152         - MHAL (Multimedia Hardware Abstraction Layer)
 153         - AV System (Audio Video Input / Output System)
 154
 155         @par
 156         Please refer to link for the further detailed description of each component.
 157
 158         @section CONCEPT        Basic Concept
 159
 160         @par
 161         Basic design concept of Multimedia Framework API will be described in this
 162         section.
 163
 164         @par
 165         1. Naming Convention
 166
 167         @par
 168         - Multimedia Framework APIs have a prefix with "MM" (stands for
 169         <B>M</B>ulti<B>M</B>edia <B>F</B>ramework). After this prefix, module name
 170         is followed by such as "MMPlayer_, MMSnd_, MMCam_".
 171
 172         @par
 173         2. Controlled by handle
 174
 175         @par
 176         - Basically Multimedia Framework manipulates each instance by handle.
 177         Camcorder Library, Attributes Library belongs to this case. Sound Library
 178         does not have instance because it applies attributes directly to system.
 179
 180         @par
 181         3. Understand Attributes
 182
 183         @par
 184         - Attributes are set of properties which each instance are configured.
 185         Basic understand is required for manipulating attributes. Please refer to
 186         @ref MMFW ATTRS LIBRARY "Attribute Library Description" to know how to use.
 187
 188         @par
 189         4. Messages
 190
 191         @par
 192         - Application can be notified that change of state, error occurs, how much
 193         time has been elapsed after playing or recording through message callback.
 194         Message callback will be called as deferred, so any API can be called in
 195         this callback function.
 196
 197         @par
 198         5. Errors
 199
 200         @par
 201         - Basically all Multimedia Framework API returns error code as return value.
 202         It returns zero (MM_ERROR_NONE) on success, or returns error code which is
 203         negative value. Each error code and range is defined in <mm_error.h> file.
 204
 205         @par
 206         6. How to build
 207
 208         @par
 209         - Each library for offering high level API will provide Package Config file
 210         to support pkg-config command. Be sure to that it will be installed on your
 211         platform SDK directory. If you want to use player library, you just append
 212         "pkg-config" line to your build script. For example, just append
 213         "pkg-config --libs --cflags mmplayer" to your build script if you want to
 214         use player library. The dependency with respect of MMPlayer is already
 215         described within package config file. Therefore, all of developers have to
 216         do is just use it by themselves.
 217 */
 218
 219 #ifdef __cplusplus
 220 }
 221 #endif
 222 /**
 223         @}
 224  */
 225 #endif  /* __MM_H__ */