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: SK_DECLARE_INST_COUNT(SkData)23 SK_DECLARE_INST_COUNT(SkData) 24 25 /** 26 * Returns the number of bytes stored. 27 */ 28 size_t size() const { return fSize; } 29 isEmpty()30 bool isEmpty() const { return 0 == fSize; } 31 32 /** 33 * Returns the ptr to the data. 34 */ data()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 */ bytes()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 */ writable_data()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 */ NewWithoutCopy(const void * data,size_t length)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 172 // Objects of this type are sometimes created in a custom fashion using sk_malloc_throw and 173 // therefore must be sk_freed. We overload new to also call sk_malloc_throw so that memory 174 // can be unconditionally released using sk_free in an overloaded delete. Overloading regular 175 // new means we must also overload placement new. new(size_t size)176 void* operator new(size_t size) { return sk_malloc_throw(size); } new(size_t,void * p)177 void* operator new(size_t, void* p) { return p; } delete(void * p)178 void operator delete(void* p) { sk_free(p); } 179 180 // Called the first time someone calls NewEmpty to initialize the singleton. 181 friend SkData* sk_new_empty_data(); 182 183 // shared internal factory 184 static SkData* PrivateNewWithCopy(const void* srcOrNull, size_t length); 185 186 typedef SkRefCnt INHERITED; 187 }; 188 189 /** Typedef of SkAutoTUnref<SkData> for automatically unref-ing a SkData. */ 190 typedef SkAutoTUnref<SkData> SkAutoDataUnref; 191 192 #endif 193