SkImage.h

Go to the documentation of this file.

/*
 * Copyright 2012 Google Inc.
 *
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */
 
#ifndef SkImage_DEFINED
#define SkImage_DEFINED
 
#include "include/core/SkImageInfo.h"
#include "include/core/SkRefCnt.h"
#include "include/core/SkSamplingOptions.h"
#include "include/core/SkScalar.h"
#include "include/core/SkShader.h"
#include "include/core/SkSurfaceProps.h"
#include "include/core/SkTileMode.h"
#if SK_SUPPORT_GPU
#include "include/gpu/GpuTypes.h"
#include "include/gpu/GrTypes.h"
#endif
#if defined(SK_GRAPHITE_ENABLED)
#include "include/gpu/graphite/GraphiteTypes.h"
#endif
 
#include <memory>
#include <functional>
#include <optional>
 
#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
#include <android/hardware_buffer.h>
#endif
 
class GrBackendFormat;
class GrBackendTexture;
class GrContextThreadSafeProxy;
class GrDirectContext;
class GrRecordingContext;
class GrYUVABackendTextureInfo;
class GrYUVABackendTextures;
class SkCanvas;
class SkData;
class SkImage;
class SkImageFilter;
class SkImageGenerator;
class SkMipmap;
class SkPaint;
class SkPicture;
class SkPixmap;
class SkPromiseImageTexture;
class SkSurface;
class SkYUVAPixmaps;
 
enum class SkEncodedImageFormat;
 
#if defined(SK_GRAPHITE_ENABLED)
namespace skgpu::graphite {
class BackendTexture;
class Recorder;
class TextureInfo;
enum class Volatile : bool;
}
#endif
 
class SK_API SkImage : public SkRefCnt {
public:
 
    typedef void* ReleaseContext;
 
    static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap);
 
    static sk_sp<SkImage> MakeRasterData(const SkImageInfo& info, sk_sp<SkData> pixels,
                                         size_t rowBytes);
 
    typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
 
    static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
                                         RasterReleaseProc rasterReleaseProc,
                                         ReleaseContext releaseContext);
 
    static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap);
 
    static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator);
 
    static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded,
                                          std::optional<SkAlphaType> alphaType = std::nullopt);
 
    /*
     * Experimental:
     *   Skia                | GL_COMPRESSED_*     | MTLPixelFormat*      | VK_FORMAT_*_BLOCK
     *  --------------------------------------------------------------------------------------
     *   kETC2_RGB8_UNORM    | ETC1_RGB8           | ETC2_RGB8 (iOS-only) | ETC2_R8G8B8_UNORM
     *                       | RGB8_ETC2           |                      |
     *  --------------------------------------------------------------------------------------
     *   kBC1_RGB8_UNORM     | RGB_S3TC_DXT1_EXT   | N/A                  | BC1_RGB_UNORM
     *  --------------------------------------------------------------------------------------
     *   kBC1_RGBA8_UNORM    | RGBA_S3TC_DXT1_EXT  | BC1_RGBA (macOS-only)| BC1_RGBA_UNORM
     */
    enum class CompressionType {
        kNone,
        kETC2_RGB8_UNORM, // the same as ETC1
 
        kBC1_RGB8_UNORM,
        kBC1_RGBA8_UNORM,
        kLast = kBC1_RGBA8_UNORM,
    };
 
    static constexpr int kCompressionTypeCount = static_cast<int>(CompressionType::kLast) + 1;
 
    static const CompressionType kETC1_CompressionType = CompressionType::kETC2_RGB8_UNORM;
 
    static sk_sp<SkImage> MakeRasterFromCompressed(sk_sp<SkData> data,
                                                   int width, int height,
                                                   CompressionType type);
 
    enum class BitDepth {
        kU8,  
        kF16, 
    };
 
    static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
                                          const SkMatrix* matrix, const SkPaint* paint,
                                          BitDepth bitDepth, sk_sp<SkColorSpace> colorSpace,
                                          SkSurfaceProps props = {});
 
#if SK_SUPPORT_GPU
    static sk_sp<SkImage> MakeTextureFromCompressed(GrDirectContext* direct,
                                                    sk_sp<SkData> data,
                                                    int width, int height,
                                                    CompressionType type,
                                                    GrMipmapped mipmapped = GrMipmapped::kNo,
                                                    GrProtected isProtected = GrProtected::kNo);
 
    typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
 
    static sk_sp<SkImage> MakeFromTexture(GrRecordingContext* context,
                                          const GrBackendTexture& backendTexture,
                                          GrSurfaceOrigin origin,
                                          SkColorType colorType,
                                          SkAlphaType alphaType,
                                          sk_sp<SkColorSpace> colorSpace,
                                          TextureReleaseProc textureReleaseProc = nullptr,
                                          ReleaseContext releaseContext = nullptr);
 
    static sk_sp<SkImage> MakeFromCompressedTexture(GrRecordingContext* context,
                                                    const GrBackendTexture& backendTexture,
                                                    GrSurfaceOrigin origin,
                                                    SkAlphaType alphaType,
                                                    sk_sp<SkColorSpace> colorSpace,
                                                    TextureReleaseProc textureReleaseProc = nullptr,
                                                    ReleaseContext releaseContext = nullptr);
 
    static sk_sp<SkImage> MakeCrossContextFromPixmap(GrDirectContext* context,
                                                     const SkPixmap& pixmap,
                                                     bool buildMips,
                                                     bool limitToMaxTextureSize = false);
 
    static sk_sp<SkImage> MakeFromAdoptedTexture(GrRecordingContext* context,
                                                 const GrBackendTexture& backendTexture,
                                                 GrSurfaceOrigin textureOrigin,
                                                 SkColorType colorType);
    static sk_sp<SkImage> MakeFromAdoptedTexture(GrRecordingContext* context,
                                                 const GrBackendTexture& backendTexture,
                                                 GrSurfaceOrigin textureOrigin,
                                                 SkColorType colorType,
                                                 SkAlphaType alphaType);
    static sk_sp<SkImage> MakeFromAdoptedTexture(GrRecordingContext* context,
                                                 const GrBackendTexture& backendTexture,
                                                 GrSurfaceOrigin textureOrigin,
                                                 SkColorType colorType,
                                                 SkAlphaType alphaType,
                                                 sk_sp<SkColorSpace> colorSpace);
 
    static sk_sp<SkImage> MakeFromYUVATextures(GrRecordingContext* context,
                                               const GrYUVABackendTextures& yuvaTextures,
                                               sk_sp<SkColorSpace> imageColorSpace = nullptr,
                                               TextureReleaseProc textureReleaseProc = nullptr,
                                               ReleaseContext releaseContext = nullptr);
 
    static sk_sp<SkImage> MakeFromYUVAPixmaps(GrRecordingContext* context,
                                              const SkYUVAPixmaps& pixmaps,
                                              GrMipmapped buildMips = GrMipmapped::kNo,
                                              bool limitToMaxTextureSize = false,
                                              sk_sp<SkColorSpace> imageColorSpace = nullptr);
 
    using PromiseImageTextureContext = void*;
    using PromiseImageTextureFulfillProc =
            sk_sp<SkPromiseImageTexture> (*)(PromiseImageTextureContext);
    using PromiseImageTextureReleaseProc = void (*)(PromiseImageTextureContext);
 
    static sk_sp<SkImage> MakePromiseTexture(sk_sp<GrContextThreadSafeProxy> gpuContextProxy,
                                             const GrBackendFormat& backendFormat,
                                             SkISize dimensions,
                                             GrMipmapped mipmapped,
                                             GrSurfaceOrigin origin,
                                             SkColorType colorType,
                                             SkAlphaType alphaType,
                                             sk_sp<SkColorSpace> colorSpace,
                                             PromiseImageTextureFulfillProc textureFulfillProc,
                                             PromiseImageTextureReleaseProc textureReleaseProc,
                                             PromiseImageTextureContext textureContext);
 
    static sk_sp<SkImage> MakePromiseYUVATexture(sk_sp<GrContextThreadSafeProxy> gpuContextProxy,
                                                 const GrYUVABackendTextureInfo& backendTextureInfo,
                                                 sk_sp<SkColorSpace> imageColorSpace,
                                                 PromiseImageTextureFulfillProc textureFulfillProc,
                                                 PromiseImageTextureReleaseProc textureReleaseProc,
                                                 PromiseImageTextureContext textureContexts[]);
 
#endif // SK_SUPPORT_GPU
 
#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
    static sk_sp<SkImage> MakeFromAHardwareBuffer(
            AHardwareBuffer* hardwareBuffer,
            SkAlphaType alphaType = kPremul_SkAlphaType,
            sk_sp<SkColorSpace> colorSpace = nullptr,
            GrSurfaceOrigin surfaceOrigin = kTopLeft_GrSurfaceOrigin);
 
    static sk_sp<SkImage> MakeFromAHardwareBufferWithData(
            GrDirectContext* context,
            const SkPixmap& pixmap,
            AHardwareBuffer* hardwareBuffer,
            GrSurfaceOrigin surfaceOrigin = kTopLeft_GrSurfaceOrigin);
#endif
 
    const SkImageInfo& imageInfo() const { return fInfo; }
 
    int width() const { return fInfo.width(); }
 
    int height() const { return fInfo.height(); }
 
    SkISize dimensions() const { return SkISize::Make(fInfo.width(), fInfo.height()); }
 
    SkIRect bounds() const { return SkIRect::MakeWH(fInfo.width(), fInfo.height()); }
 
    uint32_t uniqueID() const { return fUniqueID; }
 
    SkAlphaType alphaType() const;
 
    SkColorType colorType() const;
 
    SkColorSpace* colorSpace() const;
 
    sk_sp<SkColorSpace> refColorSpace() const;
 
    bool isAlphaOnly() const;
 
    bool isOpaque() const { return SkAlphaTypeIsOpaque(this->alphaType()); }
 
    sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions&,
                               const SkMatrix* localMatrix = nullptr) const;
 
    sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions& sampling,
                               const SkMatrix& lm) const {
        return this->makeShader(tmx, tmy, sampling, &lm);
    }
    sk_sp<SkShader> makeShader(const SkSamplingOptions& sampling, const SkMatrix& lm) const {
        return this->makeShader(SkTileMode::kClamp, SkTileMode::kClamp, sampling, &lm);
    }
    sk_sp<SkShader> makeShader(const SkSamplingOptions& sampling,
                               const SkMatrix* lm = nullptr) const {
        return this->makeShader(SkTileMode::kClamp, SkTileMode::kClamp, sampling, lm);
    }
 
    sk_sp<SkShader> makeRawShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions&,
                                  const SkMatrix* localMatrix = nullptr) const;
 
    sk_sp<SkShader> makeRawShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions& sampling,
                                  const SkMatrix& lm) const {
        return this->makeRawShader(tmx, tmy, sampling, &lm);
    }
    sk_sp<SkShader> makeRawShader(const SkSamplingOptions& sampling, const SkMatrix& lm) const {
        return this->makeRawShader(SkTileMode::kClamp, SkTileMode::kClamp, sampling, &lm);
    }
    sk_sp<SkShader> makeRawShader(const SkSamplingOptions& sampling,
                                  const SkMatrix* lm = nullptr) const {
        return this->makeRawShader(SkTileMode::kClamp, SkTileMode::kClamp, sampling, lm);
    }
 
    using CubicResampler = SkCubicResampler;
 
    bool peekPixels(SkPixmap* pixmap) const;
 
    bool isTextureBacked() const;
 
    size_t textureSize() const;
 
    bool isValid(GrRecordingContext* context) const;
 
#if SK_SUPPORT_GPU
    GrSemaphoresSubmitted flush(GrDirectContext* context, const GrFlushInfo& flushInfo) const;
 
    void flush(GrDirectContext* context) const { this->flush(context, {}); }
 
    void flushAndSubmit(GrDirectContext*) const;
 
    GrBackendTexture getBackendTexture(bool flushPendingGrContextIO,
                                       GrSurfaceOrigin* origin = nullptr) const;
#endif // SK_SUPPORT_GPU
 
    enum CachingHint {
        kAllow_CachingHint,    
        kDisallow_CachingHint, 
    };
 
    bool readPixels(GrDirectContext* context,
                    const SkImageInfo& dstInfo,
                    void* dstPixels,
                    size_t dstRowBytes,
                    int srcX, int srcY,
                    CachingHint cachingHint = kAllow_CachingHint) const;
 
    bool readPixels(GrDirectContext* context,
                    const SkPixmap& dst,
                    int srcX,
                    int srcY,
                    CachingHint cachingHint = kAllow_CachingHint) const;
 
#ifndef SK_IMAGE_READ_PIXELS_DISABLE_LEGACY_API
    bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
                    int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const;
    bool readPixels(const SkPixmap& dst, int srcX, int srcY,
                    CachingHint cachingHint = kAllow_CachingHint) const;
#endif
 
    class AsyncReadResult {
    public:
        AsyncReadResult(const AsyncReadResult&) = delete;
        AsyncReadResult(AsyncReadResult&&) = delete;
        AsyncReadResult& operator=(const AsyncReadResult&) = delete;
        AsyncReadResult& operator=(AsyncReadResult&&) = delete;
 
        virtual ~AsyncReadResult() = default;
        virtual int count() const = 0;
        virtual const void* data(int i) const = 0;
        virtual size_t rowBytes(int i) const = 0;
 
    protected:
        AsyncReadResult() = default;
    };
 
    using ReadPixelsContext = void*;
 
    using ReadPixelsCallback = void(ReadPixelsContext, std::unique_ptr<const AsyncReadResult>);
 
    enum class RescaleGamma : bool { kSrc, kLinear };
 
    enum class RescaleMode {
        kNearest,
        kLinear,
        kRepeatedLinear,
        kRepeatedCubic,
    };
 
    void asyncRescaleAndReadPixels(const SkImageInfo& info,
                                   const SkIRect& srcRect,
                                   RescaleGamma rescaleGamma,
                                   RescaleMode rescaleMode,
                                   ReadPixelsCallback callback,
                                   ReadPixelsContext context) const;
 
    void asyncRescaleAndReadPixelsYUV420(SkYUVColorSpace yuvColorSpace,
                                         sk_sp<SkColorSpace> dstColorSpace,
                                         const SkIRect& srcRect,
                                         const SkISize& dstSize,
                                         RescaleGamma rescaleGamma,
                                         RescaleMode rescaleMode,
                                         ReadPixelsCallback callback,
                                         ReadPixelsContext context) const;
 
    bool scalePixels(const SkPixmap& dst, const SkSamplingOptions&,
                     CachingHint cachingHint = kAllow_CachingHint) const;
 
    sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const;
 
    sk_sp<SkData> encodeToData() const;
 
    sk_sp<SkData> refEncodedData() const;
 
    sk_sp<SkImage> makeSubset(const SkIRect& subset, GrDirectContext* direct = nullptr) const;
 
    bool hasMipmaps() const;
 
    sk_sp<SkImage> withDefaultMipmaps() const;
 
#if SK_SUPPORT_GPU
    sk_sp<SkImage> makeTextureImage(GrDirectContext*,
                                    GrMipmapped = GrMipmapped::kNo,
                                    skgpu::Budgeted = skgpu::Budgeted::kYes) const;
#endif // SK_SUPPORT_GPU
 
#ifdef SK_GRAPHITE_ENABLED
 
    // Passed to both fulfill and imageRelease
    using GraphitePromiseImageContext = void*;
    // Returned from fulfill and passed into textureRelease
    using GraphitePromiseTextureReleaseContext = void*;
 
    using GraphitePromiseImageFulfillProc =
            std::tuple<skgpu::graphite::BackendTexture, GraphitePromiseTextureReleaseContext>
            (*)(GraphitePromiseImageContext);
    using GraphitePromiseImageReleaseProc = void (*)(GraphitePromiseImageContext);
    using GraphitePromiseTextureReleaseProc = void (*)(GraphitePromiseTextureReleaseContext);
 
    static sk_sp<SkImage> MakeGraphitePromiseTexture(skgpu::graphite::Recorder*,
                                                     SkISize dimensions,
                                                     const skgpu::graphite::TextureInfo&,
                                                     const SkColorInfo&,
                                                     skgpu::graphite::Volatile,
                                                     GraphitePromiseImageFulfillProc,
                                                     GraphitePromiseImageReleaseProc,
                                                     GraphitePromiseTextureReleaseProc,
                                                     GraphitePromiseImageContext);
 
    static sk_sp<SkImage> MakeGraphiteFromBackendTexture(skgpu::graphite::Recorder*,
                                                         const skgpu::graphite::BackendTexture&,
                                                         SkColorType colorType,
                                                         SkAlphaType alphaType,
                                                         sk_sp<SkColorSpace> colorSpace);
 
    struct RequiredImageProperties {
        skgpu::graphite::Mipmapped fMipmapped;
    };
 
    sk_sp<SkImage> makeTextureImage(skgpu::graphite::Recorder*,
                                    RequiredImageProperties = {}) const;
 
    sk_sp<SkImage> makeSubset(const SkIRect& subset,
                              skgpu::graphite::Recorder*,
                              RequiredImageProperties = {}) const;
 
    sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> targetColorSpace,
                                  skgpu::graphite::Recorder*,
                                  RequiredImageProperties = {}) const;
 
    sk_sp<SkImage> makeColorTypeAndColorSpace(SkColorType targetColorType,
                                              sk_sp<SkColorSpace> targetColorSpace,
                                              skgpu::graphite::Recorder*,
                                              RequiredImageProperties = {}) const;
 
#endif // SK_GRAPHITE_ENABLED
 
    sk_sp<SkImage> makeNonTextureImage() const;
 
    sk_sp<SkImage> makeRasterImage(CachingHint cachingHint = kDisallow_CachingHint) const;
 
    sk_sp<SkImage> makeWithFilter(GrRecordingContext* context,
                                  const SkImageFilter* filter, const SkIRect& subset,
                                  const SkIRect& clipBounds, SkIRect* outSubset,
                                  SkIPoint* offset) const;
 
    typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc;
 
#if SK_SUPPORT_GPU
    static bool MakeBackendTextureFromSkImage(GrDirectContext* context,
                                              sk_sp<SkImage> image,
                                              GrBackendTexture* backendTexture,
                                              BackendTextureReleaseProc* backendTextureReleaseProc);
#endif
    enum LegacyBitmapMode {
        kRO_LegacyBitmapMode, 
    };
 
    bool asLegacyBitmap(SkBitmap* bitmap,
                        LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const;
 
    bool isLazyGenerated() const;
 
    sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target,
                                  GrDirectContext* direct = nullptr) const;
 
    sk_sp<SkImage> makeColorTypeAndColorSpace(SkColorType targetColorType,
                                              sk_sp<SkColorSpace> targetColorSpace,
                                              GrDirectContext* direct = nullptr) const;
 
    sk_sp<SkImage> reinterpretColorSpace(sk_sp<SkColorSpace> newColorSpace) const;
 
private:
    SkImage(const SkImageInfo& info, uint32_t uniqueID);
 
    friend class SkBitmap;
    friend class SkImage_Base;   // for private ctor
    friend class SkImage_Raster; // for withMipmaps
    friend class SkMipmapBuilder;
 
    SkImageInfo     fInfo;
    const uint32_t  fUniqueID;
 
    sk_sp<SkImage> withMipmaps(sk_sp<SkMipmap>) const;
 
    using INHERITED = SkRefCnt;
};
 
#endif