Merge "Adding APIs to render PDF documents."

3 files changed, 404 insertions, 2 deletions

diff --git a/graphics/java/android/graphics/Matrix.java b/graphics/java/android/graphics/Matrix.java
index 66bf75c..b4e6bab 100644
--- a/graphics/java/android/graphics/Matrix.java
+++ b/graphics/java/android/graphics/Matrix.java
@@ -245,6 +245,16 @@ public class Matrix {
     }
 
     /**
+     * Gets whether this matrix is affine. An affine matrix preserves
+     * straight lines and has no perspective.
+     *
+     * @return Whether the matrix is affine.
+     */
+    public boolean isAffine() {
+        return native_isAffine(native_instance);
+    }
+
+    /**
      * Returns true if will map a rectangle to another rectangle. This can be
      * true if the matrix is identity, scale-only, or rotates a multiple of 90
      * degrees.
@@ -828,6 +838,7 @@ public class Matrix {
 
     private static native long native_create(long native_src_or_zero);
     private static native boolean native_isIdentity(long native_object);
+    private static native boolean native_isAffine(long native_object);
     private static native boolean native_rectStaysRect(long native_object);
     private static native void native_reset(long native_object);
     private static native void native_set(long native_object,
diff --git a/graphics/java/android/graphics/pdf/PdfDocument.java b/graphics/java/android/graphics/pdf/PdfDocument.java
index f5b07c1..d603436 100644
--- a/graphics/java/android/graphics/pdf/PdfDocument.java
+++ b/graphics/java/android/graphics/pdf/PdfDocument.java
@@ -32,7 +32,7 @@ import java.util.List;
 /**
  * <p>
  * This class enables generating a PDF document from native Android content. You
- * open a new document and then for every page you want to add you start a page,
+ * create a new document and then for every page you want to add you start a page,
  * write content to the page, and finish the page. After you are done with all
  * pages, you write the document to an output stream and close the document.
  * After a document is closed you should not use it anymore. Note that pages are
@@ -64,7 +64,7 @@ import java.util.List;
  * // write the document content
  * document.writeTo(getOutputStream());
  *
- * //close the document
+ * // close the document
  * document.close();
  * </pre>
  */
diff --git a/graphics/java/android/graphics/pdf/PdfRenderer.java b/graphics/java/android/graphics/pdf/PdfRenderer.java
new file mode 100644
index 0000000..3fa3b9f
--- /dev/null
+++ b/graphics/java/android/graphics/pdf/PdfRenderer.java
@@ -0,0 +1,391 @@
+/*
+ * Copyright (C) 2014 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.
+ */
+
+package android.graphics.pdf;
+
+import android.annotation.IntDef;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+import android.graphics.Bitmap;
+import android.graphics.Bitmap.Config;
+import android.graphics.Matrix;
+import android.graphics.Point;
+import android.graphics.Rect;
+import android.os.ParcelFileDescriptor;
+import android.system.ErrnoException;
+import android.system.OsConstants;
+import dalvik.system.CloseGuard;
+import libcore.io.Libcore;
+
+import java.io.IOException;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * <p>
+ * This class enables rendering a PDF document. This class is not thread safe.
+ * </p>
+ * <p>
+ * If you want to render a PDF, you create a renderer and for every page you want
+ * to render, you open the page, render it, and close the page. After you are done
+ * with rendering, you close the renderer. After the renderer is closed it should not
+ * be used anymore. Note that the pages are rendered one by one, i.e. you can have
+ * only a single page opened at any given time.
+ * </p>
+ * <p>
+ * A typical use of the APIs to render a PDF looks like this:
+ * </p>
+ * <pre>
+ * // create a new renderer
+ * PdfRenderer renderer = new PdfRenderer(getSeekableFileDescriptor());
+ *
+ * // let us just render all pages
+ * final int pageCount = renderer.getPageCount();
+ * for (int i = 0; i < pageCount; i++) {
+ *     Page page = renderer.openPage(i);
+ *     Bitmap bitmap = getBitmapReuseIfPossible(page);
+ *
+ *     // say we render for showing on the screen
+ *     page.render(bitmap, getContentBoundsInBitmap(),
+ *             getDesiredTransformation(), Page.RENDER_MODE_FOR_DISPLAY);
+ *
+ *     // do stuff with the bitmap
+ *
+ *     renderer.closePage(page);
+ * }
+ *
+ * // close the renderer
+ * renderer.close();
+ * </pre>
+ *
+ * @see #close()
+ */
+public final class PdfRenderer implements AutoCloseable {
+    private final CloseGuard mCloseGuard = CloseGuard.get();
+
+    private final Point mTempPoint = new Point();
+
+    private final long mNativeDocument;
+
+    private final int mPageCount;
+
+    private ParcelFileDescriptor mInput;
+
+    private Page mCurrentPage;
+
+    /** @hide */
+    @IntDef({
+        Page.RENDER_MODE_FOR_DISPLAY,
+        Page.RENDER_MODE_FOR_PRINT
+    })
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface RenderMode {}
+
+    /**
+     * Creates a new instance.
+     * <p>
+     * <strong>Note:</strong> The provided file descriptor must be <strong>seekable</strong>,
+     * i.e. its data being randomly accessed, e.g. pointing to a file.
+     * </p>
+     * <p>
+     * <strong>Note:</strong> This class takes ownership of the passed in file descriptor
+     * and is responsible for closing it when the renderer is closed.
+     * </p>
+     *
+     * @param input Seekable file descriptor to read from.
+     */
+    public PdfRenderer(@NonNull ParcelFileDescriptor input) throws IOException {
+        if (input == null) {
+            throw new NullPointerException("input cannot be null");
+        }
+
+        final long size;
+        try {
+            Libcore.os.lseek(input.getFileDescriptor(), 0, OsConstants.SEEK_SET);
+            size = Libcore.os.fstat(input.getFileDescriptor()).st_size;
+        } catch (ErrnoException ee) {
+            throw new IllegalArgumentException("file descriptor not seekable");
+        }
+
+        mInput = input;
+        mNativeDocument = nativeCreate(mInput.getFd(), size);
+        mPageCount = nativeGetPageCount(mNativeDocument);
+        mCloseGuard.open("close");
+    }
+
+    /**
+     * Closes this renderer. You should not use this instance
+     * after this method is called.
+     */
+    public void close() {
+        throwIfClosed();
+        throwIfPageOpened();
+        doClose();
+    }
+
+    /**
+     * Gets the number of pages in the document.
+     *
+     * @return The page count.
+     */
+    public int getPageCount() {
+        throwIfClosed();
+        return mPageCount;
+    }
+
+    /**
+     * Gets whether the document prefers to be scaled for printing.
+     * You should take this info account if the document is rendered
+     * for printing and the target media size differs from the page
+     * size.
+     *
+     * @return If to scale the document.
+     */
+    public boolean shouldScaleForPrinting() {
+        throwIfClosed();
+        return nativeScaleForPrinting(mNativeDocument);
+    }
+
+    /**
+     * Opens a page for rendering.
+     *
+     * @param index The page index.
+     * @return A page that can be rendered.
+     *
+     * @see #closePage(PdfRenderer.Page)
+     */
+    public Page openPage(int index) {
+        throwIfClosed();
+        throwIfPageOpened();
+        mCurrentPage = new Page(index);
+        return mCurrentPage;
+    }
+
+    /**
+     * Closes a page opened for rendering.
+     *
+     * @param page The page to close.
+     *
+     * @see #openPage(int)
+     */
+    public void closePage(@NonNull Page page) {
+        throwIfClosed();
+        throwIfNotCurrentPage(page);
+        throwIfCurrentPageClosed();
+        mCurrentPage.close();
+        mCurrentPage = null;
+    }
+
+    @Override
+    protected void finalize() throws Throwable {
+        try {
+            mCloseGuard.warnIfOpen();
+            if (mInput != null) {
+                doClose();
+            }
+        } finally {
+            super.finalize();
+        }
+    }
+
+    private void doClose() {
+        if (mCurrentPage != null) {
+            mCurrentPage.close();
+            mCurrentPage = null;
+        }
+        nativeClose(mNativeDocument);
+        try {
+            mInput.close();
+        } catch (IOException ioe) {
+            /* ignore - best effort */
+        }
+        mInput = null;
+        mCloseGuard.close();
+    }
+
+    private void throwIfClosed() {
+        if (mInput == null) {
+            throw new IllegalStateException("Already closed");
+        }
+    }
+
+    private void throwIfPageOpened() {
+        if (mCurrentPage != null) {
+            throw new IllegalStateException("Current page not closed");
+        }
+    }
+
+    private void throwIfCurrentPageClosed() {
+        if (mCurrentPage == null) {
+            throw new IllegalStateException("Already closed");
+        }
+    }
+
+    private void throwIfNotCurrentPage(Page page) {
+        if (page != mCurrentPage) {
+            throw new IllegalArgumentException("Page not from document");
+        }
+    }
+
+    /**
+     * This class represents a PDF document page for rendering.
+     */
+    public final class Page {
+
+        /**
+         * Mode to render the content for display on a screen.
+         */
+        public static final int RENDER_MODE_FOR_DISPLAY = 1;
+
+        /**
+         * Mode to render the content for printing.
+         */
+        public static final int RENDER_MODE_FOR_PRINT = 2;
+
+        private final int mIndex;
+        private final int mWidth;
+        private final int mHeight;
+
+        private long mNativePage;
+
+        private Page(int index) {
+            Point size = mTempPoint;
+            mNativePage = nativeOpenPageAndGetSize(mNativeDocument, index, size);
+            mIndex = index;
+            mWidth = size.x;
+            mHeight = size.y;
+        }
+
+        /**
+         * Gets the page index.
+         *
+         * @return The index.
+         */
+        public int getIndex() {
+            return  mIndex;
+        }
+
+        /**
+         * Gets the page width in points (1/72").
+         *
+         * @return The width in points.
+         */
+        public int getWidth() {
+            return mWidth;
+        }
+
+        /**
+         * Gets the page height in points (1/72").
+         *
+         * @return The height in points.
+         */
+        public int getHeight() {
+            return mHeight;
+        }
+
+        /**
+         * Renders a page to a bitmap.
+         * <p>
+         * You may optionally specify a rectangular clip in the bitmap bounds. No rendering
+         * outside the clip will be performed, hence it is your responsibility to initialize
+         * the bitmap outside the clip.
+         * </p>
+         * <p>
+         * You may optionally specify a matrix to transform the content from page coordinates
+         * which are in points (1/72") to bitmap coordintates which are in pixels. If this
+         * matrix is not provided this method will apply a transformation that will fit the
+         * whole page to the destination clip if profided or the destination bitmap if no
+         * clip is provided.
+         * </p>
+         * <p>
+         * The clip and transformation are useful for implementing tile rendering where the
+         * destination bitmap contains a portion of the image, for example when zooming.
+         * Another useful application is for printing where the size of the bitmap holding
+         * the page is too large and a client can render the page in stripes.
+         * </p>
+         * <p>
+         * <strong>Note: </strong> The destination bitmap format must be
+         * {@link Config#ARGB_8888 ARGB}.
+         * </p>
+         * <p>
+         * <strong>Note: </strong> The optional transformation matrix must be affine as per
+         * {@link android.graphics.Matrix#isAffine()}. Hence, you can specify rotation, scaling,
+         * translation but not a perspective transformation.
+         * </p>
+         *
+         * @param destination Destination bitmap to which to render.
+         * @param destClip Optional clip in the bitmap bounds.
+         * @param transform Optional transformation to apply when rendering.
+         * @param renderMode The render mode.
+         *
+         * @see #RENDER_MODE_FOR_DISPLAY
+         * @see #RENDER_MODE_FOR_PRINT
+         */
+        public void render(@NonNull Bitmap destination, @Nullable Rect destClip,
+                           @Nullable Matrix transform, @RenderMode int renderMode) {
+            if (destination.getConfig() != Config.ARGB_8888) {
+                throw new IllegalArgumentException("Unsupported pixel format");
+            }
+
+            if (destClip != null) {
+                if (destClip.left < 0 || destClip.top < 0
+                        || destClip.right > destination.getWidth()
+                        || destClip.bottom > destination.getHeight()) {
+                    throw new IllegalArgumentException("destBounds not in destination");
+                }
+            }
+
+            if (transform != null && !transform.isAffine()) {
+                 throw new IllegalArgumentException("transform not affine");
+            }
+
+            if (renderMode != RENDER_MODE_FOR_PRINT && renderMode != RENDER_MODE_FOR_DISPLAY) {
+                throw new IllegalArgumentException("Unsupported render mode");
+            }
+
+            if (renderMode == RENDER_MODE_FOR_PRINT && renderMode == RENDER_MODE_FOR_DISPLAY) {
+                throw new IllegalArgumentException("Only single render mode supported");
+            }
+
+            final int contentLeft = (destClip != null) ? destClip.left : 0;
+            final int contentTop = (destClip != null) ? destClip.top : 0;
+            final int contentRight = (destClip != null) ? destClip.right
+                    : destination.getWidth();
+            final int contentBottom = (destClip != null) ? destClip.bottom
+                    : destination.getHeight();
+
+            final long transformPtr = (transform != null) ? transform.native_instance : 0;
+
+            nativeRenderPage(mNativeDocument, mNativePage, destination.mNativeBitmap, contentLeft,
+                    contentTop, contentRight, contentBottom, transformPtr, renderMode);
+        }
+
+        void close() {
+            nativeClosePage(mNativePage);
+            mNativePage = 0;
+        }
+    }
+
+    private static native long nativeCreate(int fd, long size);
+    private static native void nativeClose(long documentPtr);
+    private static native int nativeGetPageCount(long documentPtr);
+    private static native boolean nativeScaleForPrinting(long documentPtr);
+    private static native void nativeRenderPage(long documentPtr, long pagePtr, long destPtr,
+            int destLeft, int destTop, int destRight, int destBottom, long matrixPtr, int renderMode);
+    private static native long nativeOpenPageAndGetSize(long documentPtr, int pageIndex,
+            Point outSize);
+    private static native void nativeClosePage(long pagePtr);
+}