Change image editing guide

This is a manual cherry-pick from the #126852 change in the tizen_3.0
branch.

Change-Id: Ie270e2f564ecc3be662ec5a408f9cae3f90085a0

diff --git a/org.tizen.guides/html/native/media/image_edit_n.htm b/org.tizen.guides/html/native/media/image_edit_n.htm
index 8b3c88d..49e541e 100644 (file)
--- a/org.tizen.guides/html/native/media/image_edit_n.htm
+++ b/org.tizen.guides/html/native/media/image_edit_n.htm
@@ -38,7 +38,8 @@
             </li>
             <li><a href="#decode">Decoding from a File or Memory</a></li>
             <li><a href="#encode">Encoding to a File or Memory</a></li>
-                       <li><a href="#color_format">Supported Colorspace Formats</a></li>
+                       <li><a href="#animation">Encoding an Animated GIF</a></li>
+                       <li><a href="#color_format">Supported Color Space Formats</a></li>
                        <li><a href="#quality">Quality and Size Comparison</a></li>
         </ul>
         <p class="toc-title">Related Info</p>
@@ -58,7 +59,7 @@
 
  <ul>
  <li>Conversion
- <p>You can <a href="#colorspace">change the colorspace format</a> among the <a href="#color_format">supported formats</a>.</p></li>
+ <p>You can <a href="#colorspace">change the color space format</a> among the <a href="#color_format">supported formats</a>.</p></li>
  <li>Resizing
 <p>You can <a href="#resize">change the image resolution</a>.</p></li>
 <li>Rotation
@@ -70,9 +71,14 @@
 <ul><li>Bitmap formats:
 <ul><li>YUV420, YUV422, RGB888, RGBA8888, BGRA8888, ARGB8888</li></ul></li>
 <li>Input image formats for decoding:
-<ul><li>Only JPEG is supported when using image util</li></ul></li>
+<ul><li>JPEG, PNG, GIF, BMP</li></ul>
+  <div class="note">
+        <strong>Note</strong>
+        Animated GIF format is not supported for decoding.
+  </div>
+</li>
 <li>Output image formats for encoding:
-<ul><li>JPEG</li></ul>
+<ul><li>JPEG, PNG, GIF, BMP, <a href="#animation">animated GIF</a></li></ul>
 <p>Pay attention to how the <a href="#quality">image quality depends on the size</a> and compression ratio.</p></li></ul>
 </li>
 </ul>
@@ -102,13 +108,14 @@ int ret = 0;
 int width = 0;
 int height = 0;
 unsigned int size_decode = 0;
+image_util_decode_h decode_h = NULL;
 </pre>
 </li>
 <li>
-<p>To find out which JPEG color spaces are supported on the device, use the <code>image_util_foreach_supported_jpeg_colorspace()</code> function:</p>
+<p>To find out which color spaces are supported on the device, use the <code>image_util_foreach_supported_colorspace()</code> function:</p>
 <pre class="prettyprint">
-int image_util_foreach_supported_jpeg_colorspace(image_util_supported_jpeg_colorspace_cb
-                                                 callback, void * user_data);
+int image_util_foreach_supported_colorspace(image_util_type_e image_type,
+                                            image_util_supported_colorspace_cb callback, void *user_data);
 </pre>
 <p>The possible color spaces are defined in the <code>image_util_colorspace_e</code> enumeration (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MEDIA__IMAGE__UTIL__MODULE.html#gad3ea89a72a617912df9ddbd50be1b991">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__MEDIA__IMAGE__UTIL__MODULE.html#gad3ea89a72a617912df9ddbd50be1b991">wearable</a> applications).</p>
 <p>For more information about the YUV color space, see <a href="http://www.fourcc.org/yuv.php" target="blank">http://www.fourcc.org/yuv.php</a>.</p>
@@ -116,8 +123,13 @@ int image_util_foreach_supported_jpeg_colorspace(image_util_supported_jpeg_color
 <li>
 <p>To support the <code>image_util_transform_run()</code> function, which is used for all image transformations, set the source image and create a handle for it (to be used as the second parameter):</p>
 <pre class="prettyprint">
-ret = image_util_decode_jpeg(SAMPLE_FILENAME, colorspace, &amp;img_source,
-                             &amp;width, &amp;height, &amp;size_decode);
+ret = image_util_decode_create(&amp;decode_h);
+ret = image_util_decode_set_input_path(decode_h, SAMPLE_FILENAME);
+ret = image_util_decode_set_colorspace(decode_h, colorspace);
+ret = image_util_decode_set_output_buffer(decode_h, &amp;img_source);
+
+ret = image_util_decode_run(decode_h, &amp;width, &amp;height, &amp;size_decode);
+ret = image_util_decode_destroy(decode_h);
 
 ret = media_format_create(&amp;fmt);
 ret = media_format_set_video_mime(fmt, colorspace);
@@ -415,15 +427,8 @@ ret = image_util_transform_run(handle, src,
 
 </li>
 
-<li>
-
-<p>Handle the transformation results in the <code>image_util_transform_completed_cb()</code> callback, which is invoked after the transformation is complete.</p>
-
-</li>
-
-<li>
-
-<p>After the transformation is complete, destroy the transformation handle using the <code>image_util_transform_destroy()</code> function:</p>
+<li><p>Handle the transformation results in the <code>image_util_transform_completed_cb()</code> callback, which is invoked after the transformation is complete.</p></li>
+<li><p>After the transformation is complete, destroy the transformation handle using the <code>image_util_transform_destroy()</code> function:</p>
 
 <pre class="prettyprint">
 ret = image_util_transform_destroy(handle);
@@ -433,67 +438,195 @@ ret = image_util_transform_destroy(handle);
 
 </ol>
 
-<h2 id="decode" name="decode">Decoding from a File or Memory</h2>
+<h2 id="decode">Decoding from a File or Memory</h2>
 
-<p>To decode a JPEG image:</p>
+<p>To decode a JPEG, PNG, GIF, or BMP image:</p>
 
-<ul>
+<ol>
 
 <li>
 
-<p>To decode the image from a file, use the <code>image_util_decode_jpeg()</code> function. Manually allocate the memory for the image buffer based on a calculated buffer size.</p>
+<p>Create a decoding handle using the <code>image_util_decode_create()</code> function:</p>
 
 <pre class="prettyprint">
-ret = image_util_decode_jpeg(SAMPLE_FILENAME, colorspace, &amp;img_source,
-                             &amp;width, &amp;height, &amp;size_decode);
+image_util_decode_h decode_h = NULL;
+ret = image_util_decode_create(decode_h);
 </pre>
 
 </li>
 
 <li>
 
-<p>To decode the image from memory, use the <code>image_util_decode_jpeg_from_memory()</code> function. Manually allocate the memory for the image buffer based on a calculated buffer size.</p>
+<p>Set the image to the input path or buffer using the <code>image_util_decode_set_input_path()</code> or <code>image_util_decode_set_input_buffer()</code> function:</p>
 
 <pre class="prettyprint">
-ret = image_util_decode_jpeg_from_memory(jpeg_buffer, jpeg_size, colorspace,
-                                         image_buffer, width, height, size);
+ret = image_util_decode_set_input_path(decode_h, path);
 </pre>
 
 </li>
 
-</ul>
-
-<h2 id="encode" name="encode">Encoding to a File or Memory</h2>
-
-<p>To encode a rotated or flipped image:</p>
-
-<ul>
+<li>
 
-<li>To encode the image to a JPEG file, use the <code>image_util_encode_jpeg()</code> function:
+<p>To save the decoded image, set the output buffer using the <code>image_util_decode_set_output_buffer()</code> function:</p>
 
 <pre class="prettyprint">
-ret = image_util_encode_jpeg(img_flip_target, dest_width, dest_height,
-                             colorspace, 100, OUTPUT_ROTATED_JPEG);
+unsigned char *result = NULL;
+ret = image_util_decode_set_output_buffer(decode_h, &amp;result);
 </pre>
 
 </li>
 
 <li>
+<p>Optionally, set the color space and JPEG downscale using the <code>image_util_decode_set_colorspace()</code> and <code>image_util_decode_set_jpeg_downscale()</code> functions:</p>
 
-<p>To encode the image to memory in the JPEG format, use the <code>image_util_encode_jpeg_to_memory()</code> function:</p>
+<pre class="prettyprint">
+unsigned char *result = NULL;
+ret = image_util_decode_set_colorspace(decode_h, IMAGE_UTIL_COLORSPACE_RGBA8888);
+ret = image_util_decode_set_jpeg_downscale(decode_h, IMAGE_UTIL_DOWNSCALE_1_1);
+</pre>
 
+  <div class="note">
+        <strong>Note</strong>
+        <ul><li>Because of decoder limitations, color space setting and JPEG downscaling are only supported for JPEG images.</li>
+        <li>The default color space is <code>IMAGE_UTIL_COLORSPACE_RGBA8888</code>. PNG, GIF and BMP images are decoded to <code>IMAGE_UTIL_COLORSPACE_RGBA8888</code>.</li></ul>
+  </div>
+</li>
+<li>
+<p>Execute the decoding using the <code>image_util_decode_run()</code> function:</p>
 <pre class="prettyprint">
-ret = image_util_encode_jpeg_to_memory(img_flip_target, dest_width, dest_height,
-                                       colorspace, 100, jpeg_buffer, jpeg_size);
+unsigned long width = 0; /* Decoded image width */
+unsigned long height = 0; /* Decoded image height */
+unsigned long long size = 0; /* Decoded image size */
+ret = image_util_decode_run(decode_h, &amp;width, &amp;height, &amp;size);
 </pre>
+</li>
+<li>
+<p>After the decoding is complete, destroy the decoding handle using the <code>image_util_decode_destroy()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_decode_destroy(decode_h);
+</pre>
+</li>
+</ol>
+<h2 id="encode">Encoding to a File or Memory</h2>
+<p>To encode a raw image:</p>
+<ol>
+<li>
+<p>Create an encoding handle using the <code>image_util_encode_create()</code> function:</p>
+<pre class="prettyprint">
+image_util_type_e encoder_type = IMAGE_UTIL_JPEG;
+image_util_encode_h encode_h = NULL;
+ret = image_util_encode_create(encoder_type, encode_h);
+</pre>
+</li>
+<li>
+<p>Set the image to the input buffer using the <code>image_util_encode_set_input_buffer()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_set_input_buffer(encode_h, buffer);
+</pre>
+</li>
+<li>
+<p>Set the width, height, and color space of the input buffer using the <code>image_util_encode_set_resolution()</code> and <code>image_util_encode_set_colorspace()</code> functions:</p>
 
+<pre class="prettyprint">
+ret = image_util_encode_set_resolution(encode_h, width, height);
+ret = image_util_encode_set_colorspace(encode_h, IMAGE_UTIL_COLORSPACE_RGBA8888);
+</pre>
+  <div class="note">
+        <strong>Note</strong>
+        <ul><li>Because of encoder limitations, color space setting is only supported for encoding JPEG images.</li>
+        <li>The default color space is <code>IMAGE_UTIL_COLORSPACE_RGBA8888</code>. PNG, GIF and BMP images are encoded with <code>IMAGE_UTIL_COLORSPACE_RGBA8888</code>.</li></ul>
+  </div>
+</li>
+<li>
+<p>To save the encoded image, set the output path or buffer using the <code>image_util_encode_set_output_path()</code> or <code>image_util_encode_set_output_buffer()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_set_output_path(encode_h, path);
+</pre>
 </li>
+<li>
+<p>Optionally, set the JPEG quality or PNG compression using the <code>image_util_encode_set_quality()</code> or <code>image_util_encode_set_png_compression()</code> function:</p>
 
-</ul>
+<pre class="prettyprint">
+ret = image_util_encode_set_jpeg_downscale(decode_h, IMAGE_UTIL_DOWNSCALE_1_1);
+</pre>
+  <div class="note">
+        <strong>Note</strong>
+        <ul><li>Because of encoder limitations, quality setting is only supported for JPEG images, and compression is only supported for PNG images.</li>
+        <li>The default JPEG quality is 75. The default PNG compression is <code>IMAGE_UTIL_PNG_COMPRESSION_6</code>.</li></ul>
+  </div>
+</li>
+<li>
+<p>Execute the encoding using the <code>image_util_encode_run()</code> function:</p>
+<pre class="prettyprint">
+unsigned long long size = 0; /* Encoded image size */
+ret = image_util_encode_run(encode_h, &amp;size);
+</pre>
+</li>
+<li>
+<p>After the encoding is complete, destroy the encoding handle using the <code>image_util_encode_destroy()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_destroy(encode_h);
+</pre>
+</li>
+</ol>
 
-<h2 id="color_format">Supported Colorspace Formats</h2>
+<h2 id="animation">Encoding an Animated GIF</h2>
+<p>To encode an animated GIF image:</p>
+<ol>
+<li>
+<p>Create an encoding handle using the <code>image_util_encode_create()</code> function:</p>
+<pre class="prettyprint">
+image_util_type_e encoder_type = IMAGE_UTIL_GIF;
+image_util_encode_h encode_h = NULL;
+ret = image_util_encode_create(encoder_type, encode_h);
+</pre>
+</li>
+<li>
+  For each frame:
+  <ol type="a">
+  <li>
+<p>Set the image to the input buffer using the <code>image_util_encode_set_input_buffer()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_set_input_buffer(encode_h, buffer);
+</pre>
+</li>
+<li>
+<p>Set the width and height of the input buffer using the <code>image_util_encode_set_resolution()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_set_resolution(encode_h, width, height);
+</pre>
+</li>
+<li>
+<p>Set the delay time between GIF frames using the <code>image_util_encode_set_gif_frame_delay_time()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_set_gif_frame_delay_time(encode_h, buffer);
+</pre>
+</li>
+</ol>
+</li>
+<li>
+<p>To save the encoded image, set the output path or buffer using the <code>image_util_encode_set_output_path()</code> or <code>image_util_encode_set_output_buffer()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_set_output_path(encode_h, path);
+</pre>
+</li>
+<li>
+<p>Execute the encoding using the <code>image_util_encode_run()</code> function:</p>
+<pre class="prettyprint">
+unsigned long long size = 0; /* Animated GIF image size */
+ret = image_util_encode_run(encode_h, &amp;size);
+</pre>
+</li>
+<li>
+<p>After the encoding is complete, destroy the encoding handle using the <code>image_util_encode_destroy()</code> function:</p>
+<pre class="prettyprint">
+ret = image_util_encode_destroy(encode_h);
+</pre>
+</li>
+</ol>
+<h2 id="color_format">Supported Color Space Formats</h2>
 
-<p>The following tables define the supported colorspace formats.</p>
+<p>The following tables define the supported color space formats.</p>
    <p align="center" class="Table"><strong>Table: RGB pixel formats</strong></p>
    <table>
    <tbody>