include/c/sk_surface.h

   1 /*
   2  * Copyright 2014 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 // EXPERIMENTAL EXPERIMENTAL EXPERIMENTAL EXPERIMENTAL
   9 // DO NOT USE -- FOR INTERNAL TESTING ONLY
  10
  11 #ifndef sk_surface_DEFINED
  12 #define sk_surface_DEFINED
  13
  14 #include "sk_types.h"
  15
  16 SK_C_PLUS_PLUS_BEGIN_GUARD
  17
  18 /**
  19     Return the default sk_colortype_t; this is operating-system dependent.
  20 */
  21 SK_API sk_colortype_t sk_colortype_get_default_8888();
  22
  23 /**
  24     Return a new surface, with the memory for the pixels automatically
  25     allocated.  If the requested surface cannot be created, or the
  26     request is not a supported configuration, NULL will be returned.
  27
  28     @param sk_imageinfo_t* Specify the width, height, color type, and
  29                            alpha type for the surface.
  30
  31     @param sk_surfaceprops_t* If not NULL, specify additional non-default
  32                               properties of the surface.
  33 */
  34 SK_API sk_surface_t* sk_surface_new_raster(const sk_imageinfo_t*, const sk_surfaceprops_t*);
  35
  36 /**
  37     Create a new surface which will draw into the specified pixels
  38     with the specified rowbytes.  If the requested surface cannot be
  39     created, or the request is not a supported configuration, NULL
  40     will be returned.
  41
  42     @param sk_imageinfo_t* Specify the width, height, color type, and
  43                            alpha type for the surface.
  44     @param void* pixels Specify the location in memory where the
  45                         destination pixels are.  This memory must
  46                         outlast this surface.
  47      @param size_t rowBytes Specify the difference, in bytes, between
  48                            each adjacent row.  Should be at least
  49                            (width * sizeof(one pixel)).
  50     @param sk_surfaceprops_t* If not NULL, specify additional non-default
  51                               properties of the surface.
  52 */
  53 SK_API sk_surface_t* sk_surface_new_raster_direct(const sk_imageinfo_t*, void* pixels, size_t rowBytes, const sk_surfaceprops_t* props);
  54
  55 /**
  56     Decrement the reference count. If the reference count is 1 before
  57     the decrement, then release both the memory holding the
  58     sk_surface_t and any pixel memory it may be managing.  New
  59     sk_surface_t are created with a reference count of 1.
  60 */
  61 SK_API void sk_surface_unref(sk_surface_t*);
  62
  63 /**
  64  *  Return the canvas associated with this surface. Note: the canvas is owned by the surface,
  65  *  so the returned object is only valid while the owning surface is valid.
  66  */
  67 SK_API sk_canvas_t* sk_surface_get_canvas(sk_surface_t*);
  68
  69 /**
  70  *  Call sk_image_unref() when the returned image is no longer used.
  71  */
  72 SK_API sk_image_t* sk_surface_new_image_snapshot(sk_surface_t*);
  73
  74 /**
  75  *  Used to wrap a pre-existing 3D API rendering target as a SkSurface. Skia will not assume
  76  *  ownership of the render target and the client must ensure the render target is valid for the
  77  *  lifetime of the SkSurface.
  78  */
  79 SK_API sk_surface_t* sk_surface_new_backend_render_target(gr_context_t* context, const gr_backend_rendertarget_desc_t* desc, const sk_surfaceprops_t* props);
  80
  81 /**
  82  *  Used to wrap a pre-existing backend 3D API texture as a SkSurface. The kRenderTarget flag
  83  *  must be set on GrBackendTextureDesc for this to succeed. Skia will not assume ownership
  84  *  of the texture and the client must ensure the texture is valid for the lifetime of the
  85  *  SkSurface.
  86  */
  87 SK_API sk_surface_t* sk_surface_new_backend_texture(gr_context_t* context, const gr_backend_texture_desc_t* desc, const sk_surfaceprops_t* props);
  88
  89 /**
  90  *  Used to wrap a pre-existing 3D API texture as a SkSurface. Skia will treat the texture as
  91  *  a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
  92  *  the associated render target objects (but not the provided texture). The kRenderTarget flag
  93  *  must be set on GrBackendTextureDesc for this to succeed. Skia will not assume ownership
  94  *  of the texture and the client must ensure the texture is valid for the lifetime of the
  95  *  SkSurface.
  96  */
  97 SK_API sk_surface_t* sk_surface_new_backend_texture_as_render_target(gr_context_t* context, const gr_backend_texture_desc_t* desc, const sk_surfaceprops_t* props);
  98
  99 SK_API sk_surface_t* sk_surface_new_render_target(gr_context_t* context, bool budgeted, const sk_imageinfo_t* info, int sampleCount, const sk_surfaceprops_t* props);
 100
 101 SK_C_PLUS_PLUS_END_GUARD
 102
 103 #endif