Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit d84c652a authored by Leon Scroggins III's avatar Leon Scroggins III
Browse files

Update javadocs for ImageDecoder and related 

Bug: 76461699
Bug: 76448408
Test: No change in behavior, no new tests

Add class level docs for ImageDecoder, including sample code. Update
wording to be more clear and less wordy. Fix broken attempts at using
sample code.

Incorporate advice at go/android-api-guidelines and
https://developers.google.com/style/api-reference-comments

Change-Id: Iaf1334993f6cd2d3f6e53d3fb70ef9c7a95c9a76
parent d9b53a09

graphics/java/android/graphics/ImageDecoder.java

+265 −102

File changed.

Preview size limit exceeded, changes collapsed.

graphics/java/android/graphics/PostProcessor.java

+44 −42
Original line number Diff line number Diff line
@@ -16,25 +16,26 @@ 


package android.graphics;



import android.annotation.IntDef;

import android.annotation.NonNull;

import android.graphics.drawable.AnimatedImageDrawable;

import android.graphics.drawable.Drawable;



/**

 *  Helper interface for adding custom processing to an image.

 *

 *  <p>The image being processed may be a {@link Drawable}, {@link Bitmap} or frame

 *  of an animated image produced by {@link ImageDecoder}. This is called before

 *  the requested object is returned.</p>

 *  <p>The image being processed may be a {@link Drawable}, a {@link Bitmap}, or

 *  a frame of an {@link AnimatedImageDrawable} produced by {@link ImageDecoder}.

 *  This is called before the requested object is returned.</p>

 *

 *  <p>This custom processing also applies to image types that are otherwise

 *  immutable, such as {@link Bitmap.Config#HARDWARE}.</p>

 *  <p>This custom processing can even be applied to images that will be returned

 *  as immutable objects, such as a {@link Bitmap} with {@code Config}

 *  {@link Bitmap.Config#HARDWARE} returned by {@link ImageDecoder}.</p>

 *

 *  <p>On an animated image, the callback will only be called once, but the drawing

 *  commands will be applied to each frame, as if the {@code Canvas} had been

 *  returned by {@link Picture#beginRecording}.<p>

 *  <p>On an {@link AnimatedImageDrawable}, the callback will only be called once,

 *  but the drawing commands will be applied to each frame, as if the {@link Canvas}

 *  had been returned by {@link Picture#beginRecording Picture.beginRecording}.<p>

 *

 *  <p>Supplied to ImageDecoder via {@link ImageDecoder#setPostProcessor}.</p>

 *  <p>Supplied to ImageDecoder via {@link ImageDecoder#setPostProcessor setPostProcessor}.</p>

 */

public interface PostProcessor {

    /**
@@ -43,11 +44,11 @@ public interface PostProcessor { 
     *  <p>Drawing to the {@link Canvas} will behave as if the initial processing

     *  (e.g. decoding) already exists in the Canvas. An implementation can draw

     *  effects on top of this, or it can even draw behind it using

     *  {@link PorterDuff.Mode#DST_OVER}. A common effect is to add transparency

     *  to the corners to achieve rounded corners. That can be done with the

     *  following code:</p>

     *  {@link PorterDuff.Mode#DST_OVER PorterDuff.Mode.DST_OVER}. A common

     *  effect is to add transparency to the corners to achieve rounded corners.

     *  That can be done with the following code:</p>

     *

     *  <code>

     *  <pre class="prettyprint">

     *  Path path = new Path();

     *  path.setFillType(Path.FillType.INVERSE_EVEN_ODD);

     *  int width = canvas.getWidth();
@@ -59,27 +60,28 @@ public interface PostProcessor { 
     *  paint.setXfermode(new PorterDuffXfermode(PorterDuff.Mode.SRC));

     *  canvas.drawPath(path, paint);

     *  return PixelFormat.TRANSLUCENT;

     *  </code>

     *  </pre>

     *

     *

     *  @param canvas The {@link Canvas} to draw to.

     *  @return Opacity of the result after drawing.

     *      {@link PixelFormat#UNKNOWN} means that the implementation did not

     *      change whether the image has alpha. Return this unless you added

     *      transparency (e.g. with the code above, in which case you should

     *      return {@code PixelFormat.TRANSLUCENT}) or you forced the image to

     *      be opaque (e.g. by drawing everywhere with an opaque color and

     *      {@code PorterDuff.Mode.DST_OVER}, in which case you should return

     *      {@code PixelFormat.OPAQUE}).

     *      {@link PixelFormat#TRANSLUCENT} means that the implementation added

     *      transparency. This is safe to return even if the image already had

     *      transparency. This is also safe to return if the result is opaque,

     *      though it may draw more slowly.

     *      {@link PixelFormat#OPAQUE} means that the implementation forced the

     *      image to be opaque. This is safe to return even if the image was

     *      already opaque.

     *      {@link PixelFormat#TRANSPARENT} (or any other integer) is not

     *      allowed, and will result in throwing an

     *      {@link PixelFormat#UNKNOWN PixelFormat.UNKNOWN} means that the

     *      implementation did not change whether the image has alpha. Return

     *      this unless you added transparency (e.g. with the code above, in

     *      which case you should return

     *      {@link PixelFormat#TRANSLUCENT PixelFormat.TRANSLUCENT}) or you

     *      forced the image to be opaque (e.g. by drawing everywhere with an

     *      opaque color and {@link PorterDuff.Mode#DST_OVER PorterDuff.Mode.DST_OVER},

     *      in which case you should return {@link PixelFormat#OPAQUE PixelFormat.OPAQUE}).

     *      {@link PixelFormat#TRANSLUCENT PixelFormat.TRANSLUCENT} means that

     *      the implementation added transparency. This is safe to return even

     *      if the image already had transparency. This is also safe to return

     *      if the result is opaque, though it may draw more slowly.

     *      {@link PixelFormat#OPAQUE PixelFormat.OPAQUE} means that the

     *      implementation forced the image to be opaque. This is safe to return

     *      even if the image was already opaque.

     *      {@link PixelFormat#TRANSPARENT PixelFormat.TRANSPARENT} (or any other

     *      integer) is not allowed, and will result in throwing an

     *      {@link java.lang.IllegalArgumentException}.

     */

    @PixelFormat.Opacity