s.a.c. redesign, first checkin
Change-Id: I4dead2f18bc5e4a38f204c92198a267c286e775d
diff --git a/src/devices/camera.jd b/src/devices/camera.jd
new file mode 100644
index 0000000..1e709c8
--- /dev/null
+++ b/src/devices/camera.jd
@@ -0,0 +1,174 @@
+page.title=Camera Version 1
+@jd:body
+
+<!--
+ Copyright 2010 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>Android's camera HAL connects the higher level
+camera framework APIs in <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> to your underlying camera driver and hardware.
+The following figure and list describe the components involved and where to find the source for each:
+</p>
+
+<p><img src="images/camera_hal.png"></p>
+
+<dl>
+
+ <dt>Application framework</dt>
+ <dd>At the application framework level is the app's code, which utilizes the <a
+ href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>
+ API to interact with the camera hardware. Internally, this code calls a corresponding JNI glue class
+ to access the native code that interacts with the camera.</dd>
+
+ <dt>JNI</dt>
+ <dd>The JNI code associated with <a
+ href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> is located in
+ <code>frameworks/base/core/jni/android_hardware_Camera.cpp</code>. This code calls the lower level
+ native code to obtain access to the physical camera and returns data that is used to create the
+ <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> object at the framework level.</dd>
+
+ <dt>Native framework<dt>
+ <dd>The native framework defined in <code>frameworks/av/camera/Camera.cpp</code> provides a native equivalent
+ to the <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> class.
+ This class calls the IPC binder proxies to obtain access to the camera service.</dd>
+
+ <dt>Binder IPC proxies</dt>
+ <dd>The IPC binder proxies facilitate communication over process boundaries. There are three camera binder
+ classes that are located in the <code>frameworks/av/camera</code> directory that calls into
+ camera service. ICameraService is the interface to the camera service, ICamera is the interface
+ to a specific opened camera device, and ICameraClient is the device's interface back to the application framework.</dd>
+
+ <dt>Camera service</dt>
+ <dd>The camera service, located in <code>frameworks/av/services/camera/libcameraservice/CameraService.cpp</code>, is the actual code that interacts with the HAL.</p>
+
+ <dt>HAL</dt>
+ <dd>The hardware abstraction layer defines the standard interface that the camera service calls into and that
+ you must implement to have your camera hardware function correctly.
+ </dd>
+
+ <dt>Kernel driver</dt>
+ <dd>The camera's driver interacts with the actual camera hardware and your implementation of the HAL. The
+ camera and driver must support YV12 and NV21 image formats to provide support for
+ previewing the camera image on the display and video recording.</dd>
+ </dl>
+
+
+<h2 id="implementing">Implementing the HAL</h2>
+<p>The HAL sits between the camera driver and the higher level Android framework
+and defines an interface that you must implement so that apps can
+correctly operate the camera hardware. The HAL interface is defined in the
+<code>hardware/libhardware/include/hardware/camera.h</code> and
+<code>hardware/libhardware/include/hardware/camera_common.h</code> header files.
+</p>
+
+<p>
+<code>camera_common.h</code> defines an important struct, <code>camera_module</code>, which defines a standard
+structure to obtain general information about the camera, such as its ID and properties
+that are common to all cameras such as whether or not it is a front or back-facing camera.
+</p>
+
+<p>
+<code>camera.h</code> contains the code that corresponds mainly with
+<a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>. This header file declares a <code>camera_device</code>
+struct that contains a <code>camera_device_ops</code> struct with function pointers
+that point to functions that implement the HAL interface. For documentation on the
+different types of camera parameters that a developer can set,
+see the <code>frameworks/av/include/camera/CameraParameters.h</code> file.
+These parameters are set with the function pointed to by
+<code>int (*set_parameters)(struct camera_device *, const char *parms)</code> in the HAL.
+</p>
+
+<p>For an example of a HAL implementation, see the implementation for the Galaxy Nexus HAL in
+<code>hardware/ti/omap4xxx/camera</code>.</p>
+
+
+<h2 id="configuring">Configuring the Shared Library</h2>
+<p>You need to set up the Android build system to
+ correctly package the HAL implementation into a shared library and copy it to the
+ appropriate location by creating an <code>Android.mk</code> file:
+
+<ol>
+ <li>Create a <code>device/<company_name>/<device_name>/camera</code> directory to contain your
+ library's source files.</li>
+ <li>Create an <code>Android.mk</code> file to build the shared library. Ensure that the Makefile contains the following lines:
+<pre>
+LOCAL_MODULE := camera.<device_name>
+LOCAL_MODULE_PATH := $(TARGET_OUT_SHARED_LIBRARIES)/hw
+</pre>
+<p>Notice that your library must be named <code>camera.<device_name></code> (<code>.so</code> is appended automatically),
+so that Android can correctly load the library. For an example, see the Makefile
+for the Galaxy Nexus camera located in <code>hardware/ti/omap4xxx/Android.mk</code>.</p>
+
+</li>
+<li>Specify that your device has camera features by copying the necessary feature XML files in the
+<code>frameworks/native/data/etc</code> directory with your
+device's Makefile. For example, to specify that your device has a camera flash and can autofocus,
+add the following lines in your device's
+<code><device>/<company_name>/<device_name>/device.mk</code> Makefile:
+
+<pre class="no-pretty-print">
+PRODUCT_COPY_FILES := \ ...
+
+PRODUCT_COPY_FILES += \
+frameworks/native/data/etc/android.hardware.camera.flash-autofocus.xml:system/etc/permissions/android.hardware.camera.flash-autofocus.xml \
+</pre>
+
+<p>For an example of a device Makefile, see <code>device/samsung/tuna/device.mk</code>.</p>
+</li>
+
+<li>Declare your camera’s media codec, format, and resolution capabilities in
+<code>device/<company_name>/<device_name>/media_profiles.xml</code> and
+<code>device/<company_name>/<device_name>/media_codecs.xml</code> XML files.
+ For more information, see <a href="{@docRoot}guide/media.html#expose"> Exposing
+ Codecs and Profiles to the Framework</a> for information on how to do this.
+</p></code>
+
+</li>
+
+<li>Add the following lines in your device's
+ <code>device/<company_name>/<device_name>/device.mk</code>
+ Makefile to copy the <code>media_profiles.xml</code>
+and <code>media_codecs.xml</code> files to the appropriate location:
+<pre>
+# media config xml file
+PRODUCT_COPY_FILES += \
+ <device>/<company_name>/<device_name>/media_profiles.xml:system/etc/media_profiles.xml
+
+# media codec config xml file
+PRODUCT_COPY_FILES += \
+ <device>/<company_name>/<device_name>/media_codecs.xml:system/etc/media_codecs.xml
+</pre>
+</li>
+
+<li>
+<p>Declare that you want to include the Camera app in your device's system image by
+specifying it in the <code>PRODUCT_PACKAGES</code> variable in your device's
+ <code>device/<company_name>/<device_name>/device.mk</code>
+ Makefile:</p>
+<pre>
+PRODUCT_PACKAGES := \
+Gallery2 \
+...
+</pre>
+</li>
+
+</ol>
\ No newline at end of file