// After editing this file, run "go generate" in the parent directory. // Copyright 2017 The Wuffs Authors. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // Wuffs assumes that: // - converting a uint32_t to a size_t will never overflow. // - converting a size_t to a uint64_t will never overflow. #ifdef __WORDSIZE #if (__WORDSIZE != 32) && (__WORDSIZE != 64) #error "Wuffs requires a word size of either 32 or 64 bits" #endif #endif // WUFFS_VERSION is the major.minor.patch version, as per https://semver.org/, // as a uint64_t. The major number is the high 32 bits. The minor number is the // middle 16 bits. The patch number is the low 16 bits. The pre-release label // and build metadata are part of the string representation (such as // "1.2.3-beta+456.20181231") but not the uint64_t representation. // // WUFFS_VERSION_PRE_RELEASE_LABEL (such as "", "beta" or "rc.1") being // non-empty denotes a developer preview, not a release version, and has no // backwards or forwards compatibility guarantees. // // WUFFS_VERSION_BUILD_METADATA_XXX, if non-zero, are the number of commits and // the last commit date in the repository used to build this library. Within // each major.minor branch, the commit count should increase monotonically. // // !! Some code generation programs can override WUFFS_VERSION. #define WUFFS_VERSION ((uint64_t)0) #define WUFFS_VERSION_MAJOR ((uint64_t)0) #define WUFFS_VERSION_MINOR ((uint64_t)0) #define WUFFS_VERSION_PATCH ((uint64_t)0) #define WUFFS_VERSION_PRE_RELEASE_LABEL "work.in.progress" #define WUFFS_VERSION_BUILD_METADATA_COMMIT_COUNT 0 #define WUFFS_VERSION_BUILD_METADATA_COMMIT_DATE 0 #define WUFFS_VERSION_STRING "0.0.0+0.00000000" // Define WUFFS_CONFIG__STATIC_FUNCTIONS to make all of Wuffs' functions have // static storage. The motivation is discussed in the "ALLOW STATIC // IMPLEMENTATION" section of // https://raw.githubusercontent.com/nothings/stb/master/docs/stb_howto.txt #ifdef WUFFS_CONFIG__STATIC_FUNCTIONS #define WUFFS_BASE__MAYBE_STATIC static #else #define WUFFS_BASE__MAYBE_STATIC #endif #if defined(__clang__) #define WUFFS_BASE__POTENTIALLY_UNUSED_FIELD __attribute__((unused)) #else #define WUFFS_BASE__POTENTIALLY_UNUSED_FIELD #endif // Clang also defines "__GNUC__". #if defined(__GNUC__) #define WUFFS_BASE__POTENTIALLY_UNUSED __attribute__((unused)) #define WUFFS_BASE__WARN_UNUSED_RESULT __attribute__((warn_unused_result)) #else #define WUFFS_BASE__POTENTIALLY_UNUSED #define WUFFS_BASE__WARN_UNUSED_RESULT #endif // Flags for wuffs_foo__bar__initialize functions. #define WUFFS_INITIALIZE__DEFAULT_OPTIONS ((uint32_t)0x00000000) // WUFFS_INITIALIZE__ALREADY_ZEROED means that the "self" receiver struct value // has already been set to all zeroes. #define WUFFS_INITIALIZE__ALREADY_ZEROED ((uint32_t)0x00000001) // WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED means that, absent // WUFFS_INITIALIZE__ALREADY_ZEROED, only some of the "self" receiver struct // value will be set to all zeroes. Internal buffers, which tend to be a large // proportion of the struct's size, will be left uninitialized. Internal means // that the buffer is contained by the receiver struct, as opposed to being // passed as a separately allocated "work buffer". // // With or without this bit set, the Wuffs compiler still enforces that no // reads or writes will overflow internal buffers' bounds. Even with this bit // set, the Wuffs standard library also considers reading from an uninitialized // buffer to be a bug, and strives to never do so, but unlike buffer overflows, // it is not a bug class that the Wuffs compiler eliminates. // // For those paranoid about security, leave this bit unset, so that // wuffs_foo__bar__initialize will initialize the entire struct value to zeroes // (unless WUFFS_INITIALIZE__ALREADY_ZEROED is set). // // Setting this bit gives a small absolute improvement on micro-benchmarks, but // this can be a large relative effect, up to 2x faster, when the actual work // to be done is also small, such as decompressing small input. See git commit // 438fc105 "Move some struct fields to private_data" for some numbers and a // discussion, noting that its commit message was written before this // WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED option was defined. #define WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED \ ((uint32_t)0x00000002) // -------- // wuffs_base__empty_struct is used when a Wuffs function returns an empty // struct. In C, if a function f returns void, you can't say "x = f()", but in // Wuffs, if a function g returns empty, you can say "y = g()". typedef struct { // private_impl is a placeholder field. It isn't explicitly used, except that // without it, the sizeof a struct with no fields can differ across C/C++ // compilers, and it is undefined behavior in C99. For example, gcc says that // the sizeof an empty struct is 0, and g++ says that it is 1. This leads to // ABI incompatibility if a Wuffs .c file is processed by one compiler and // its .h file with another compiler. // // Instead, we explicitly insert an otherwise unused field, so that the // sizeof this struct is always 1. uint8_t private_impl; } wuffs_base__empty_struct; static inline wuffs_base__empty_struct // wuffs_base__make_empty_struct() { wuffs_base__empty_struct ret; ret.private_impl = 0; return ret; } // wuffs_base__utility is a placeholder receiver type. It enables what Java // calls static methods, as opposed to regular methods. typedef struct { // private_impl is a placeholder field. It isn't explicitly used, except that // without it, the sizeof a struct with no fields can differ across C/C++ // compilers, and it is undefined behavior in C99. For example, gcc says that // the sizeof an empty struct is 0, and g++ says that it is 1. This leads to // ABI incompatibility if a Wuffs .c file is processed by one compiler and // its .h file with another compiler. // // Instead, we explicitly insert an otherwise unused field, so that the // sizeof this struct is always 1. uint8_t private_impl; } wuffs_base__utility; // -------- // A status is either NULL (meaning OK) or a string message. That message is // human-readable, for programmers, but it is not for end users. It is not // localized, and does not contain additional contextual information such as a // source filename. // // Status strings are statically allocated and should never be free'd. They can // be compared by the == operator and not just by strcmp. // // Statuses come in four categories: // - OK: the request was completed, successfully. // - Warnings: the request was completed, unsuccessfully. // - Suspensions: the request was not completed, but can be re-tried. // - Errors: the request was not completed, permanently. // // When a function returns an incomplete status, a suspension means that that // function should be called again within a new context, such as after flushing // or re-filling an I/O buffer. An error means that an irrecoverable failure // state was reached. typedef const char* wuffs_base__status; // !! INSERT wuffs_base__status names. static inline bool // wuffs_base__status__is_complete(wuffs_base__status z) { return (z == NULL) || ((*z != '$') && (*z != '#')); } static inline bool // wuffs_base__status__is_error(wuffs_base__status z) { return z && (*z == '#'); } static inline bool // wuffs_base__status__is_ok(wuffs_base__status z) { return z == NULL; } static inline bool // wuffs_base__status__is_suspension(wuffs_base__status z) { return z && (*z == '$'); } static inline bool // wuffs_base__status__is_warning(wuffs_base__status z) { return z && (*z != '$') && (*z != '#'); } // -------- // FourCC constants. // !! INSERT FourCCs. // -------- // Flicks are a unit of time. One flick (frame-tick) is 1 / 705_600_000 of a // second. See https://github.com/OculusVR/Flicks typedef int64_t wuffs_base__flicks; #define WUFFS_BASE__FLICKS_PER_SECOND ((uint64_t)705600000) #define WUFFS_BASE__FLICKS_PER_MILLISECOND ((uint64_t)705600) // ---------------- Numeric Types static inline uint8_t // wuffs_base__u8__min(uint8_t x, uint8_t y) { return x < y ? x : y; } static inline uint8_t // wuffs_base__u8__max(uint8_t x, uint8_t y) { return x > y ? x : y; } static inline uint16_t // wuffs_base__u16__min(uint16_t x, uint16_t y) { return x < y ? x : y; } static inline uint16_t // wuffs_base__u16__max(uint16_t x, uint16_t y) { return x > y ? x : y; } static inline uint32_t // wuffs_base__u32__min(uint32_t x, uint32_t y) { return x < y ? x : y; } static inline uint32_t // wuffs_base__u32__max(uint32_t x, uint32_t y) { return x > y ? x : y; } static inline uint64_t // wuffs_base__u64__min(uint64_t x, uint64_t y) { return x < y ? x : y; } static inline uint64_t // wuffs_base__u64__max(uint64_t x, uint64_t y) { return x > y ? x : y; } // -------- // Saturating arithmetic (sat_add, sat_sub) branchless bit-twiddling algorithms // are per https://locklessinc.com/articles/sat_arithmetic/ // // It is important that the underlying types are unsigned integers, as signed // integer arithmetic overflow is undefined behavior in C. static inline uint8_t // wuffs_base__u8__sat_add(uint8_t x, uint8_t y) { uint8_t res = (uint8_t)(x + y); res |= (uint8_t)(-(res < x)); return res; } static inline uint8_t // wuffs_base__u8__sat_sub(uint8_t x, uint8_t y) { uint8_t res = (uint8_t)(x - y); res &= (uint8_t)(-(res <= x)); return res; } static inline uint16_t // wuffs_base__u16__sat_add(uint16_t x, uint16_t y) { uint16_t res = (uint16_t)(x + y); res |= (uint16_t)(-(res < x)); return res; } static inline uint16_t // wuffs_base__u16__sat_sub(uint16_t x, uint16_t y) { uint16_t res = (uint16_t)(x - y); res &= (uint16_t)(-(res <= x)); return res; } static inline uint32_t // wuffs_base__u32__sat_add(uint32_t x, uint32_t y) { uint32_t res = (uint32_t)(x + y); res |= (uint32_t)(-(res < x)); return res; } static inline uint32_t // wuffs_base__u32__sat_sub(uint32_t x, uint32_t y) { uint32_t res = (uint32_t)(x - y); res &= (uint32_t)(-(res <= x)); return res; } static inline uint64_t // wuffs_base__u64__sat_add(uint64_t x, uint64_t y) { uint64_t res = (uint64_t)(x + y); res |= (uint64_t)(-(res < x)); return res; } static inline uint64_t // wuffs_base__u64__sat_sub(uint64_t x, uint64_t y) { uint64_t res = (uint64_t)(x - y); res &= (uint64_t)(-(res <= x)); return res; } // ---------------- Slices and Tables // WUFFS_BASE__SLICE is a 1-dimensional buffer. // // len measures a number of elements, not necessarily a size in bytes. // // A value with all fields NULL or zero is a valid, empty slice. #define WUFFS_BASE__SLICE(T) \ struct { \ T* ptr; \ size_t len; \ } // WUFFS_BASE__TABLE is a 2-dimensional buffer. // // width height, and stride measure a number of elements, not necessarily a // size in bytes. // // A value with all fields NULL or zero is a valid, empty table. #define WUFFS_BASE__TABLE(T) \ struct { \ T* ptr; \ size_t width; \ size_t height; \ size_t stride; \ } typedef WUFFS_BASE__SLICE(uint8_t) wuffs_base__slice_u8; typedef WUFFS_BASE__SLICE(uint16_t) wuffs_base__slice_u16; typedef WUFFS_BASE__SLICE(uint32_t) wuffs_base__slice_u32; typedef WUFFS_BASE__SLICE(uint64_t) wuffs_base__slice_u64; typedef WUFFS_BASE__TABLE(uint8_t) wuffs_base__table_u8; typedef WUFFS_BASE__TABLE(uint16_t) wuffs_base__table_u16; typedef WUFFS_BASE__TABLE(uint32_t) wuffs_base__table_u32; typedef WUFFS_BASE__TABLE(uint64_t) wuffs_base__table_u64; static inline wuffs_base__slice_u8 // wuffs_base__make_slice_u8(uint8_t* ptr, size_t len) { wuffs_base__slice_u8 ret; ret.ptr = ptr; ret.len = len; return ret; } static inline wuffs_base__slice_u16 // wuffs_base__make_slice_u16(uint16_t* ptr, size_t len) { wuffs_base__slice_u16 ret; ret.ptr = ptr; ret.len = len; return ret; } static inline wuffs_base__slice_u32 // wuffs_base__make_slice_u32(uint32_t* ptr, size_t len) { wuffs_base__slice_u32 ret; ret.ptr = ptr; ret.len = len; return ret; } static inline wuffs_base__slice_u64 // wuffs_base__make_slice_u64(uint64_t* ptr, size_t len) { wuffs_base__slice_u64 ret; ret.ptr = ptr; ret.len = len; return ret; } static inline wuffs_base__slice_u8 // wuffs_base__null_slice_u8() { wuffs_base__slice_u8 ret; ret.ptr = NULL; ret.len = 0; return ret; } static inline wuffs_base__table_u8 // wuffs_base__null_table_u8() { wuffs_base__table_u8 ret; ret.ptr = NULL; ret.width = 0; ret.height = 0; ret.stride = 0; return ret; } // wuffs_base__slice_u8__subslice_i returns s[i:]. // // It returns an empty slice if i is out of bounds. static inline wuffs_base__slice_u8 // wuffs_base__slice_u8__subslice_i(wuffs_base__slice_u8 s, uint64_t i) { if ((i <= SIZE_MAX) && (i <= s.len)) { return wuffs_base__make_slice_u8(s.ptr + i, s.len - i); } return wuffs_base__make_slice_u8(NULL, 0); } // wuffs_base__slice_u8__subslice_j returns s[:j]. // // It returns an empty slice if j is out of bounds. static inline wuffs_base__slice_u8 // wuffs_base__slice_u8__subslice_j(wuffs_base__slice_u8 s, uint64_t j) { if ((j <= SIZE_MAX) && (j <= s.len)) { return wuffs_base__make_slice_u8(s.ptr, j); } return wuffs_base__make_slice_u8(NULL, 0); } // wuffs_base__slice_u8__subslice_ij returns s[i:j]. // // It returns an empty slice if i or j is out of bounds. static inline wuffs_base__slice_u8 // wuffs_base__slice_u8__subslice_ij(wuffs_base__slice_u8 s, uint64_t i, uint64_t j) { if ((i <= j) && (j <= SIZE_MAX) && (j <= s.len)) { return wuffs_base__make_slice_u8(s.ptr + i, j - i); } return wuffs_base__make_slice_u8(NULL, 0); }