Making DALi public API typesafe using guaranteed types; uint8_t, uint32_t

[platform/core/uifw/dali-core.git] / dali / public-api / images / native-image-interface.h

diff --git a/dali/public-api/images/native-image-interface.h b/dali/public-api/images/native-image-interface.h
index b347bef..a3b4531 100644 (file)
--- a/dali/public-api/images/native-image-interface.h
+++ b/dali/public-api/images/native-image-interface.h
@@ -2,7 +2,7 @@
 #define __DALI_INTEGRATION_NATIVE_IMAGE_INTERFACE_H__
 
 /*
- * Copyright (c) 2015 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2018 Samsung Electronics Co., Ltd.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,50 +18,65 @@
  *
  */
 
+// EXTERNAL INCLUDES
+#include <cstddef>
+#include <cstdint> // uint32_t
+
 // INTERNAL INCLUDES
 #include <dali/public-api/object/ref-object.h>
 
 namespace Dali
 {
+/**
+ * @addtogroup dali_core_images
+ * @{
+ */
 
 /**
  * @brief Abstract interface to provide platform-specific support for handling image data.
  *
  * For example, an implementation could use EGL extensions, etc.
+ * @SINCE_1_0.0
  */
 class NativeImageInterface : public Dali::RefObject
 {
 public:
 
+  class Extension; ///< Forward declare future extension interface
+
   /**
-   * @brief Create the GL resource for the NativeImage.
+   * @brief Creates the GL resource for the NativeImage.
    *
-   * e.g. For the EglImageKHR extension, this corresponds to calling eglCreateImageKHR()
+   * e.g. For the EglImageKHR extension, this corresponds to calling eglCreateImageKHR().
+   * @SINCE_1_0.0
+   * @return false If the initialization fails
    * @pre There is a GL context for the current thread.
-   * @return false If the initialization fails.
    */
   virtual bool GlExtensionCreate() = 0;
 
   /**
-   * @brief Destroy the GL resource for the NativeImage.
+   * @brief Destroys the GL resource for the NativeImage.
    *
-   * e.g. For the EglImageKHR extension, this corresponds to calling eglDestroyImageKHR()
+   * e.g. For the EglImageKHR extension, this corresponds to calling eglDestroyImageKHR().
+   * @SINCE_1_0.0
    * @pre There is a GL context for the current thread.
    */
   virtual void GlExtensionDestroy() = 0;
 
   /**
-   * @brief Use the NativeImage as a texture for rendering.
+   * @brief Uses the NativeImage as a texture for rendering.
    *
-   * @pre There is a GL context for the current thread.
+   * @SINCE_1_0.0
    * @return A GL error code
+   * @pre There is a GL context for the current thread.
    */
-  virtual unsigned int TargetTexture() = 0;
+  virtual uint32_t TargetTexture() = 0;
 
   /**
-   * @brief Called in each NativeTexture::Bind() call to allow implementation specific operations.
+   * @brief Called internally for each Bind call for this texture to allow implementation specific operations.
    *
    * The correct texture sampler has already been bound before the function gets called.
+   * @SINCE_1_0.0
    * @pre glAbstraction is being used by context in current thread
    */
   virtual void PrepareTexture() = 0;
@@ -69,28 +84,44 @@ public:
   /**
    * @brief Returns the width of the NativeImage.
    *
-   * @return width
+   * @SINCE_1_0.0
+   * @return Width
    */
-  virtual unsigned int GetWidth() const = 0;
+  virtual uint32_t GetWidth() const = 0;
 
   /**
    * @brief Returns the height of the NativeImage.
    *
-   * @return height
+   * @SINCE_1_0.0
+   * @return Height
    */
-  virtual unsigned int GetHeight() const = 0;
+  virtual uint32_t GetHeight() const = 0;
 
  /**
-  * Query whether blending is required
+  * @brief Queries whether blending is required.
+  * @SINCE_1_0.0
+  * @return True if blending is required
   */
   virtual bool RequiresBlending() const = 0;
 
+  /**
+   * @brief Retrieves the extension for the interface.
+   *
+   * @SINCE_1_0.0
+   * @return The extension if available, NULL otherwise
+   */
+  virtual Extension* GetExtension()
+  {
+    return NULL;
+  }
+
 protected:
 
   /**
    * @brief A reference counted object may only be deleted by calling Unreference().
    *
    * The implementation should destroy the NativeImage resources.
+   * @SINCE_1_0.0
    */
   virtual ~NativeImageInterface()
   {
@@ -99,10 +130,14 @@ protected:
 };
 
 /**
- * @brief Pointer to Dali::NativeImageInterface
+ * @brief Pointer to Dali::NativeImageInterface.
+ * @SINCE_1_0.0
  */
-typedef IntrusivePtr<NativeImageInterface>  NativeImageInterfacePtr;
+typedef Dali::IntrusivePtr<NativeImageInterface>  NativeImageInterfacePtr;
 
+/**
+ * @}
+ */
 } // namespace Dali
 
 #endif // __DALI_INTEGRATION_NATIVE_IMAGE_INTERFACE_H__