SkImagePriv.h revision f6782442ba2aff9a0b18078e154c7bcc0a434abd 
1/*
2 * Copyright 2012 Google Inc.
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8#ifndef SkImagePriv_DEFINED
9#define SkImagePriv_DEFINED
10
11#include "SkImage.h"
12#include "SkSurface.h"
13
14enum SkCopyPixelsMode {
15    kIfMutable_SkCopyPixelsMode,  //!< only copy src pixels if they are marked mutable
16    kAlways_SkCopyPixelsMode,     //!< always copy src pixels (even if they are marked immutable)
17    kNever_SkCopyPixelsMode,      //!< never copy src pixels (even if they are marked mutable)
18};
19
20// A good size for creating shader contexts on the stack.
21enum {kSkBlitterContextSize = 3332};
22
23// If alloc is non-nullptr, it will be used to allocate the returned SkShader, and MUST outlive
24// the SkShader.
25sk_sp<SkShader> SkMakeBitmapShader(const SkBitmap& src, SkShader::TileMode, SkShader::TileMode,
26                                   const SkMatrix* localMatrix, SkCopyPixelsMode);
27
28/**
29 *  Examines the bitmap to decide if it can share the existing pixelRef, or
30 *  if it needs to make a deep-copy of the pixels.
31 *
32 *  The bitmap's pixelref will be shared if either the bitmap is marked as
33 *  immutable, or CopyPixelsMode allows it. Shared pixel refs are also
34 *  locked when kLocked_SharedPixelRefMode is specified.
35 *
36 *  Passing kLocked_SharedPixelRefMode allows the image's peekPixels() method
37 *  to succeed, but it will force any lazy decodes/generators to execute if
38 *  they exist on the pixelref.
39 *
40 *  It is illegal to call this with a texture-backed bitmap.
41 *
42 *  If the bitmap's colortype cannot be converted into a corresponding
43 *  SkImageInfo, or the bitmap's pixels cannot be accessed, this will return
44 *  nullptr.
45 */
46extern sk_sp<SkImage> SkMakeImageFromRasterBitmap(const SkBitmap&, SkCopyPixelsMode);
47
48// Given an image created from SkNewImageFromBitmap, return its pixelref. This
49// may be called to see if the surface and the image share the same pixelref,
50// in which case the surface may need to perform a copy-on-write.
51extern const SkPixelRef* SkBitmapImageGetPixelRef(const SkImage* rasterImage);
52
53/**
54 *  Will attempt to upload and lock the contents of the image as a texture, so that subsequent
55 *  draws to a gpu-target will come from that texture (and not by looking at the original image
56 *  src). In particular this is intended to use the texture even if the image's original content
57 *  changes subsequent to this call (i.e. the src is mutable!).
58 *
59 *  All successful calls must be balanced by an equal number of calls to SkImage_unpinAsTexture().
60 *
61 *  Once in this "pinned" state, the image has all of the same thread restrictions that exist
62 *  for a natively created gpu image (e.g. SkImage::MakeFromTexture)
63 *  - all drawing, pinning, unpinning must happen in the same thread as the GrContext.
64 *
65 *  @return true if the image was successfully uploaded and locked into a texture
66 */
67bool SkImage_pinAsTexture(const SkImage*, GrContext*);
68
69/**
70 *  The balancing call to a successful invokation of SkImage_pinAsTexture.  When a balanced number of
71 *  calls have been made, then the "pinned" texture is free to be purged, etc. This also means that a
72 *  subsequent "pin" call will look at the original content again, and if its uniqueID/generationID
73 *  has changed, then a newer texture will be uploaded/pinned.
74 *
75 *  The context passed to unpin must match the one passed to pin.
76 */
77void SkImage_unpinAsTexture(const SkImage*, GrContext*);
78
79/**
80 *  Returns a new image containing the same pixel values as the source, but with a different color
81 *  space assigned. This performs no color space conversion. Primarily used in tests, to visualize
82 *  the results of rendering in wide or narrow gamuts.
83 */
84sk_sp<SkImage> SkImageMakeRasterCopyAndAssignColorSpace(const SkImage*, SkColorSpace*);
85
86#endif
87