michael@0: /*
michael@0:  * Copyright 2013 Google Inc.
michael@0:  *
michael@0:  * Use of this source code is governed by a BSD-style license that can be
michael@0:  * found in the LICENSE file.
michael@0:  */
michael@0: 
michael@0: #ifndef SkError_DEFINED
michael@0: #define SkError_DEFINED
michael@0: 
michael@0: 
michael@0: /** \file SkError.h
michael@0: */
michael@0: 
michael@0: enum SkError {
michael@0:     /** All is well
michael@0:      */
michael@0:     kNoError_SkError=0,
michael@0: 
michael@0:     /** User argument passed to Skia function was invalid: NULL when that’s
michael@0:      *  not allowed, out of numeric range, bad enum, or violating some
michael@0:      *  other general precondition.
michael@0:      */
michael@0:     kInvalidArgument_SkError,
michael@0: 
michael@0:     /** User tried to perform some operation in a state when the operation
michael@0:      *  was not legal, or the operands make no sense (e.g., asking for
michael@0:      *  pixels from an SkPictureCanvas).  Other examples might be
michael@0:      *  inset()’ing a rectangle to make it degenerate (negative width/height).
michael@0:      */
michael@0:     kInvalidOperation_SkError,
michael@0: 
michael@0:     /** Probably not needed right now, but in the future we could have opaque
michael@0:      *  handles for SkPictures floating around, and it would be a good idea
michael@0:      *  to anticipate this kind of issue.
michael@0:      */
michael@0:     kInvalidHandle_SkError,
michael@0: 
michael@0:     /** This is probably not possible because paint surely has defaults for
michael@0:      *  everything, but perhaps a paint can get into a bad state somehow.
michael@0:      */
michael@0:     kInvalidPaint_SkError,
michael@0: 
michael@0:     /** Skia was unable to allocate memory to perform some task.
michael@0:      */
michael@0:     kOutOfMemory_SkError,
michael@0: 
michael@0:     /** Skia failed while trying to consume some external resource.
michael@0:      */
michael@0:     kParseError_SkError,
michael@0: 
michael@0:     /** Something went wrong internally; could be resource exhaustion but
michael@0:       * will often be a bug.
michael@0:      */
michael@0:     kInternalError_SkError
michael@0: };
michael@0: 
michael@0: /** Return the current per-thread error code.  Error codes are "sticky"; they
michael@0:  *  are not not reset by subsequent successful operations.
michael@0:  */
michael@0: SkError SkGetLastError();
michael@0: 
michael@0: /** Clear the current per-thread error code back to kNoError_SkError.
michael@0:  */
michael@0: void SkClearLastError();
michael@0: 
michael@0: /** Type for callback functions to be invoked whenever an error is registered.
michael@0:  *  Callback functions take the error code being set, as well as a context
michael@0:  *  argument that is provided when the callback is registered.
michael@0:  */
michael@0: typedef void (*SkErrorCallbackFunction)(SkError, void *);
michael@0: 
michael@0: /** Set the current per-thread error callback.
michael@0:  *
michael@0:  *  @param cb The callback function to be invoked.  Passing NULL
michael@0:  *            for cb will revert to the default error callback which
michael@0:  *            does nothing on release builds, but on debug builds will
michael@0:  *            print an informative error message to the screen.
michael@0:  *  @param context An arbitrary pointer that will be passed to
michael@0:  *                 the provided callback function.
michael@0:  */
michael@0: void SkSetErrorCallback(SkErrorCallbackFunction cb, void *context);
michael@0: 
michael@0: /** Get a human-readable description of the last (per-thread) error that
michael@0:  *  occurred.  The returned error message will include not only a human
michael@0:  *  readable version of the error code, but also information about the
michael@0:  *  conditions that led to the error itself.
michael@0:  */
michael@0: const char *SkGetLastErrorString();
michael@0: 
michael@0: #endif /* SkError_DEFINED */