From 530ffd0b7d3c39757b20f00716e486b5caf89aff Mon Sep 17 00:00:00 2001 From: sanine Date: Wed, 12 Oct 2022 12:03:23 -0500 Subject: add cairo --- libs/cairo-1.16.0/doc/public/xml/cairo-version.xml | 278 +++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 libs/cairo-1.16.0/doc/public/xml/cairo-version.xml (limited to 'libs/cairo-1.16.0/doc/public/xml/cairo-version.xml') diff --git a/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml b/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml new file mode 100644 index 0000000..7825ecd --- /dev/null +++ b/libs/cairo-1.16.0/doc/public/xml/cairo-version.xml @@ -0,0 +1,278 @@ + + +]> + + +Version Information +3 +CAIRO Library + + +Version Information +Compile-time and run-time version checks. + + + +Functions + + + + + +#defineCAIRO_VERSION_ENCODE() +#defineCAIRO_VERSION_STRINGIZE() +int +cairo_version () +const char * +cairo_version_string () + + + + + + +Types and Values + + + + + +#defineCAIRO_VERSION +#defineCAIRO_VERSION_MAJOR +#defineCAIRO_VERSION_MINOR +#defineCAIRO_VERSION_MICRO +#defineCAIRO_VERSION_STRING + + + + + + + + +Description +Cairo has a three-part version number scheme. In this scheme, we use +even vs. odd numbers to distinguish fixed points in the software +vs. in-progress development, (such as from git instead of a tar file, +or as a "snapshot" tar file as opposed to a "release" tar file). + + _____ Major. Always 1, until we invent a new scheme. +/ ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (git) +| / _ Micro. Even/Odd = Tar-file/git +| | / +1.0.0 + +Here are a few examples of versions that one might see. + +Releases +-------- +1.0.0 - A major release +1.0.2 - A subsequent maintenance release +1.2.0 - Another major release +  +Snapshots +--------- +1.1.2 - A snapshot (working toward the 1.2.0 release) +  +In-progress development (eg. from git) +-------------------------------------- +1.0.1 - Development on a maintenance branch (toward 1.0.2 release) +1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release) + + +Compatibility + +The API/ABI compatibility guarantees for various versions are as +follows. First, let's assume some cairo-using application code that is +successfully using the API/ABI "from" one version of cairo. Then let's +ask the question whether this same code can be moved "to" the API/ABI +of another version of cairo. + +Moving from a release to any later version (release, snapshot, +development) is always guaranteed to provide compatibility. + +Moving from a snapshot to any later version is not guaranteed to +provide compatibility, since snapshots may introduce new API that ends +up being removed before the next release. + +Moving from an in-development version (odd micro component) to any +later version is not guaranteed to provide compatibility. In fact, +there's not even a guarantee that the code will even continue to work +with the same in-development version number. This is because these +numbers don't correspond to any fixed state of the software, but +rather the many states between snapshots and releases. + + + +Examining the version + +Cairo provides the ability to examine the version at either +compile-time or run-time and in both a human-readable form as well as +an encoded form suitable for direct comparison. Cairo also provides the +macro CAIRO_VERSION_ENCODE() to perform the encoding. + + +Compile-time +------------ +CAIRO_VERSION_STRING Human-readable +CAIRO_VERSION Encoded, suitable for comparison +  +Run-time +-------- +cairo_version_string() Human-readable +cairo_version() Encoded, suitable for comparison + + +For example, checking that the cairo version is greater than or equal +to 1.0.0 could be achieved at compile-time or run-time as follows: + + +##if CAIRO_VERSION >= CAIRO_VERSION_ENCODE(1, 0, 0) +printf ("Compiling with suitable cairo version: %s\n", %CAIRO_VERSION_STRING); +##endif + +if (cairo_version() >= CAIRO_VERSION_ENCODE(1, 0, 0)) + printf ("Running with suitable cairo version: %s\n", cairo_version_string ()); + + + + + + +Functions + +CAIRO_VERSION_ENCODE() +CAIRO_VERSION_ENCODE +#define CAIRO_VERSION_ENCODE(major, minor, micro) +This macro encodes the given cairo version into an integer. The numbers +returned by CAIRO_VERSION and cairo_version() are encoded using this macro. +Two encoded version numbers can be compared as integers. The encoding ensures +that later versions compare greater than earlier versions. + +Parameters + + + + + + +major +the major component of the version number + +minor +the minor component of the version number + +micro +the micro component of the version number + + + +Returns + the encoded version. +Since: 1.0 + +CAIRO_VERSION_STRINGIZE() +CAIRO_VERSION_STRINGIZE +#define CAIRO_VERSION_STRINGIZE(major, minor, micro) +This macro encodes the given cairo version into an string. The numbers +returned by CAIRO_VERSION_STRING and cairo_version_string() are encoded using this macro. +The parameters to this macro must expand to numerical literals. + +Parameters + + + + + + +major +the major component of the version number + +minor +the minor component of the version number + +micro +the micro component of the version number + + + +Returns + a string literal containing the version. +Since: 1.8 + +cairo_version () +cairo_version +int +cairo_version (void); +Returns the version of the cairo library encoded in a single +integer as per CAIRO_VERSION_ENCODE. The encoding ensures that +later versions compare greater than earlier versions. +A run-time comparison to check that cairo's version is greater than +or equal to version X.Y.Z could be performed as follows: + +if (cairo_version() >= CAIRO_VERSION_ENCODE(X,Y,Z)) {...} + +See also cairo_version_string() as well as the compile-time +equivalents CAIRO_VERSION and CAIRO_VERSION_STRING. + +Returns + the encoded version. +Since: 1.0 + +cairo_version_string () +cairo_version_string +const char * +cairo_version_string (void); +Returns the version of the cairo library as a human-readable string +of the form "X.Y.Z". +See also cairo_version() as well as the compile-time equivalents +CAIRO_VERSION_STRING and CAIRO_VERSION. + +Returns + a string containing the version. +Since: 1.0 + + + +Types and Values + +CAIRO_VERSION +CAIRO_VERSION +#define CAIRO_VERSION +The version of cairo available at compile-time, encoded using +CAIRO_VERSION_ENCODE(). +Since: 1.0 + +CAIRO_VERSION_MAJOR +CAIRO_VERSION_MAJOR +#define CAIRO_VERSION_MAJOR USE_cairo_version_OR_cairo_version_string_INSTEAD + +The major component of the version of cairo available at compile-time. +Since: 1.0 + +CAIRO_VERSION_MINOR +CAIRO_VERSION_MINOR +#define CAIRO_VERSION_MINOR USE_cairo_version_OR_cairo_version_string_INSTEAD + +The minor component of the version of cairo available at compile-time. +Since: 1.0 + +CAIRO_VERSION_MICRO +CAIRO_VERSION_MICRO +#define CAIRO_VERSION_MICRO USE_cairo_version_OR_cairo_version_string_INSTEAD + +The micro component of the version of cairo available at compile-time. +Since: 1.0 + +CAIRO_VERSION_STRING +CAIRO_VERSION_STRING +#define CAIRO_VERSION_STRING +A human-readable string literal containing the version of cairo available +at compile-time, in the form of "X.Y.Z". +Since: 1.8 + + + + -- cgit v1.2.1