src/third_party/skia/include/core/SkData.h

   1 /*
   2  * Copyright 2011 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 SkData_DEFINED
   9 #define SkData_DEFINED
  10
  11 #include "SkRefCnt.h"
  12
  13 struct SkFILE;
  14 class SkStream;
  15
  16 /**
  17  *  SkData holds an immutable data buffer. Not only is the data immutable,
  18  *  but the actual ptr that is returned (by data() or bytes()) is guaranteed
  19  *  to always be the same for the life of this instance.
  20  */
  21 class SK_API SkData : public SkRefCnt {
  22 public:
  23     SK_DECLARE_INST_COUNT(SkData)
  24
  25     /**
  26      *  Returns the number of bytes stored.
  27      */
  28     size_t size() const { return fSize; }
  29
  30     bool isEmpty() const { return 0 == fSize; }
  31
  32     /**
  33      *  Returns the ptr to the data.
  34      */
  35     const void* data() const { return fPtr; }
  36
  37     /**
  38      *  Like data(), returns a read-only ptr into the data, but in this case
  39      *  it is cast to uint8_t*, to make it easy to add an offset to it.
  40      */
  41     const uint8_t* bytes() const {
  42         return reinterpret_cast<const uint8_t*>(fPtr);
  43     }
  44
  45     /**
  46      *  USE WITH CAUTION.
  47      *  This call will assert that the refcnt is 1, as a precaution against modifying the
  48      *  contents when another client/thread has access to the data.
  49      */
  50     void* writable_data() {
  51         if (fSize) {
  52             // only assert we're unique if we're not empty
  53             SkASSERT(this->unique());
  54         }
  55         return fPtr;
  56     }
  57
  58     /**
  59      *  Helper to copy a range of the data into a caller-provided buffer.
  60      *  Returns the actual number of bytes copied, after clamping offset and
  61      *  length to the size of the data. If buffer is NULL, it is ignored, and
  62      *  only the computed number of bytes is returned.
  63      */
  64     size_t copyRange(size_t offset, size_t length, void* buffer) const;
  65
  66     /**
  67      *  Returns true if these two objects have the same length and contents,
  68      *  effectively returning 0 == memcmp(...)
  69      */
  70     bool equals(const SkData* other) const;
  71
  72     /**
  73      *  Function that, if provided, will be called when the SkData goes out
  74      *  of scope, allowing for custom allocation/freeing of the data.
  75      */
  76     typedef void (*ReleaseProc)(const void* ptr, size_t length, void* context);
  77
  78     /**
  79      *  Create a new dataref by copying the specified data
  80      */
  81     static SkData* NewWithCopy(const void* data, size_t length);
  82
  83     /**
  84      *  Create a new data with uninitialized contents. The caller should call writable_data()
  85      *  to write into the buffer, but this must be done before another ref() is made.
  86      */
  87     static SkData* NewUninitialized(size_t length);
  88
  89     /**
  90      *  Create a new dataref by copying the specified c-string
  91      *  (a null-terminated array of bytes). The returned SkData will have size()
  92      *  equal to strlen(cstr) + 1. If cstr is NULL, it will be treated the same
  93      *  as "".
  94      */
  95     static SkData* NewWithCString(const char cstr[]);
  96
  97     /**
  98      *  Create a new dataref, taking the data ptr as is, and using the
  99      *  releaseproc to free it. The proc may be NULL.
 100      */
 101     static SkData* NewWithProc(const void* data, size_t length, ReleaseProc proc, void* context);
 102
 103     /**
 104      *  Call this when the data parameter is already const and will outlive the lifetime of the
 105      *  SkData. Suitable for with const globals.
 106      */
 107     static SkData* NewWithoutCopy(const void* data, size_t length) {
 108         return NewWithProc(data, length, NULL, NULL);
 109     }
 110
 111     /**
 112      *  Create a new dataref from a pointer allocated by malloc. The Data object
 113      *  takes ownership of that allocation, and will handling calling sk_free.
 114      */
 115     static SkData* NewFromMalloc(const void* data, size_t length);
 116
 117     /**
 118      *  Create a new dataref the file with the specified path.
 119      *  If the file cannot be opened, this returns NULL.
 120      */
 121     static SkData* NewFromFileName(const char path[]);
 122
 123     /**
 124      *  Create a new dataref from a SkFILE.
 125      *  This does not take ownership of the SkFILE, nor close it.
 126      *  The caller is free to close the SkFILE at its convenience.
 127      *  The SkFILE must be open for reading only.
 128      *  Returns NULL on failure.
 129      */
 130     static SkData* NewFromFILE(SkFILE* f);
 131
 132     /**
 133      *  Create a new dataref from a file descriptor.
 134      *  This does not take ownership of the file descriptor, nor close it.
 135      *  The caller is free to close the file descriptor at its convenience.
 136      *  The file descriptor must be open for reading only.
 137      *  Returns NULL on failure.
 138      */
 139     static SkData* NewFromFD(int fd);
 140
 141     /**
 142      *  Attempt to read size bytes into a SkData. If the read succeeds, return the data,
 143      *  else return NULL. Either way the stream's cursor may have been changed as a result
 144      *  of calling read().
 145      */
 146     static SkData* NewFromStream(SkStream*, size_t size);
 147
 148     /**
 149      *  Create a new dataref using a subset of the data in the specified
 150      *  src dataref.
 151      */
 152     static SkData* NewSubset(const SkData* src, size_t offset, size_t length);
 153
 154     /**
 155      *  Returns a new empty dataref (or a reference to a shared empty dataref).
 156      *  New or shared, the caller must see that unref() is eventually called.
 157      */
 158     static SkData* NewEmpty();
 159
 160 private:
 161     ReleaseProc fReleaseProc;
 162     void*       fReleaseProcContext;
 163
 164     void*       fPtr;
 165     size_t      fSize;
 166
 167     SkData(const void* ptr, size_t size, ReleaseProc, void* context);
 168     SkData(size_t size);   // inplace new/delete
 169     virtual ~SkData();
 170
 171     virtual void internal_dispose() const SK_OVERRIDE;
 172
 173     // Called the first time someone calls NewEmpty to initialize the singleton.
 174     static SkData* NewEmptyImpl();
 175     static void DeleteEmpty(SkData*);
 176
 177     // shared internal factory
 178     static SkData* PrivateNewWithCopy(const void* srcOrNull, size_t length);
 179
 180     typedef SkRefCnt INHERITED;
 181 };
 182
 183 /** Typedef of SkAutoTUnref<SkData> for automatically unref-ing a SkData. */
 184 typedef SkAutoTUnref<SkData> SkAutoDataUnref;
 185
 186 #endif