chromium/third_party/skia/include/core/SkSurface.h

/*
 * 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 SkSurface_DEFINED
#define SkSurface_DEFINED

#include "include/core/SkImage.h"
#include "include/core/SkImageInfo.h"
#include "include/core/SkPixmap.h"
#include "include/core/SkRefCnt.h"
#include "include/core/SkSamplingOptions.h"
#include "include/core/SkScalar.h"
#include "include/core/SkSurfaceProps.h"
#include "include/core/SkTypes.h"

#include <cstddef>
#include <cstdint>
#include <memory>

class GrBackendSemaphore;
class GrBackendTexture;
class GrRecordingContext;
class GrSurfaceCharacterization;
enum GrSurfaceOrigin : int;
class SkBitmap;
class SkCanvas;
class SkCapabilities;
class SkColorSpace;
class SkPaint;
class SkSurface;
struct SkIRect;
struct SkISize;

namespace skgpu::graphite {
class Recorder;
}

namespace SkSurfaces {

enum class BackendSurfaceAccess { … };

/** Returns SkSurface without backing pixels. Drawing to SkCanvas returned from SkSurface
    has no effect. Calling makeImageSnapshot() on returned SkSurface returns nullptr.

    @param width   one or greater
    @param height  one or greater
    @return        SkSurface if width and height are positive; otherwise, nullptr

    example: https://fiddle.skia.org/c/@Surface_MakeNull
*/
SK_API sk_sp<SkSurface> Null(int width, int height);

/** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into those allocated
    pixels, which are zeroed before use. Pixel memory size is imageInfo.height() times
    imageInfo.minRowBytes() or rowBytes, if provided and non-zero.

    Pixel memory is deleted when SkSurface is deleted.

    Validity constraints include:
      - info dimensions are greater than zero;
      - info contains SkColorType and SkAlphaType supported by raster surface.

    @param imageInfo  width, height, SkColorType, SkAlphaType, SkColorSpace,
                      of raster surface; width and height must be greater than zero
    @param rowBytes   interval from one SkSurface row to the next.
    @param props      LCD striping orientation and setting for device independent fonts;
                      may be nullptr
    @return           SkSurface if parameters are valid and memory was allocated, else nullptr.
*/
SK_API sk_sp<SkSurface> Raster(const SkImageInfo& imageInfo,
                               size_t rowBytes,
                               const SkSurfaceProps* surfaceProps);
inline sk_sp<SkSurface> Raster(const SkImageInfo& imageInfo,
                               const SkSurfaceProps* props = nullptr) { … }

/** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into the
    provided pixels.

    SkSurface is returned if all parameters are valid.
    Valid parameters include:
    info dimensions are greater than zero;
    info contains SkColorType and SkAlphaType supported by raster surface;
    pixels is not nullptr;
    rowBytes is large enough to contain info width pixels of SkColorType.

    Pixel buffer size should be info height times computed rowBytes.
    Pixels are not initialized.
    To access pixels after drawing, peekPixels() or readPixels().

    @param imageInfo     width, height, SkColorType, SkAlphaType, SkColorSpace,
                         of raster surface; width and height must be greater than zero
    @param pixels        pointer to destination pixels buffer
    @param rowBytes      interval from one SkSurface row to the next
    @param surfaceProps  LCD striping orientation and setting for device independent fonts;
                         may be nullptr
    @return              SkSurface if all parameters are valid; otherwise, nullptr
*/

SK_API sk_sp<SkSurface> WrapPixels(const SkImageInfo& imageInfo,
                                   void* pixels,
                                   size_t rowBytes,
                                   const SkSurfaceProps* surfaceProps = nullptr);
inline sk_sp<SkSurface> WrapPixels(const SkPixmap& pm, const SkSurfaceProps* props = nullptr) { … }

PixelsReleaseProc;

/** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into the provided
    pixels. releaseProc is called with pixels and context when SkSurface is deleted.

    SkSurface is returned if all parameters are valid.
    Valid parameters include:
    info dimensions are greater than zero;
    info contains SkColorType and SkAlphaType supported by raster surface;
    pixels is not nullptr;
    rowBytes is large enough to contain info width pixels of SkColorType.

    Pixel buffer size should be info height times computed rowBytes.
    Pixels are not initialized.
    To access pixels after drawing, call flush() or peekPixels().

    @param imageInfo     width, height, SkColorType, SkAlphaType, SkColorSpace,
                         of raster surface; width and height must be greater than zero
    @param pixels        pointer to destination pixels buffer
    @param rowBytes      interval from one SkSurface row to the next
    @param releaseProc   called when SkSurface is deleted; may be nullptr
    @param context       passed to releaseProc; may be nullptr
    @param surfaceProps  LCD striping orientation and setting for device independent fonts;
                         may be nullptr
    @return              SkSurface if all parameters are valid; otherwise, nullptr
*/
SK_API sk_sp<SkSurface> WrapPixels(const SkImageInfo& imageInfo,
                                   void* pixels,
                                   size_t rowBytes,
                                   PixelsReleaseProc,
                                   void* context,
                                   const SkSurfaceProps* surfaceProps = nullptr);
}  // namespace SkSurfaces

/** \class SkSurface
    SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
    allocated either in CPU memory (a raster surface) or on the GPU (a GrRenderTarget surface).
    SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
    surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface).
    SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
    of the requested dimensions are zero, then nullptr will be returned.

    Clients should *not* subclass SkSurface as there is a lot of internal machinery that is
    not publicly accessible.
*/
class SK_API SkSurface : public SkRefCnt { … };

#endif