Updating headers for latest trunk (1.3 stable)

Author: adamjs

AppCore/JSHelpers.h

@@ -45,16 +45,16 @@ class AExport JSString {
   /// Create from Ultralight String
   JSString(const String& str);
 
-  /// Take ownership of existing JSStringRef (will not increase ref-count)
+  /// Create from existing JSStringRef
   JSString(JSStringRef str);
 
-  /// Copy constructor (will increase ref-count)
+  /// Copy constructor 
   JSString(const JSString& other);
 
   /// Destructor
   ~JSString();
 
-  /// Assignment operator (will increase ref-count)
+  /// Assignment operator 
   JSString& operator=(const JSString& other);
 
   /// Cast to String

AppCore/Window.h

@@ -16,6 +16,9 @@
 #include <Ultralight/RefPtr.h>
 #include <Ultralight/Listener.h>
 #include <Ultralight/Bitmap.h>
+#include <Ultralight/KeyEvent.h>
+#include <Ultralight/MouseEvent.h>
+#include <Ultralight/ScrollEvent.h>
 
 namespace ultralight {
 
@@ -34,7 +37,7 @@ class WindowListener {
   ///
   /// Called when the Window is closed.
   ///
-  virtual void OnClose(ultralight::Window* window) = 0;
+  virtual void OnClose(ultralight::Window* window) { }
 
   ///
   /// Called when the Window is resized.
@@ -43,7 +46,34 @@ class WindowListener {
   ///
   /// @param  height  The new height (in pixels).
   ///
-  virtual void OnResize(ultralight::Window* window, uint32_t width_px, uint32_t height_px) = 0;
+  virtual void OnResize(ultralight::Window* window, uint32_t width_px, uint32_t height_px) { }
+
+  ///
+  /// Called when a keyboard event is fired.
+  /// 
+  /// @param  evt  Details for the event.
+  /// 
+  /// @return  Return false to consume the event and prevent it from propagating further.
+  /// 
+  virtual bool OnKeyEvent(const ultralight::KeyEvent& evt) { return true; }
+
+  ///
+  /// Called when a mouse event is fired.
+  ///
+  /// @param  evt  Details for the event.
+  ///
+  /// @return  Return false to consume the event and prevent it from propagating further.
+  /// 
+  virtual bool OnMouseEvent(const ultralight::MouseEvent& evt) { return true; }
+
+  ///
+  /// Called when a scroll event is fired.
+  ///
+  /// @param  evt  Details for the event.
+  ///
+  /// @return  Return false to consume the event and prevent it from propagating further.
+  /// 
+  virtual bool OnScrollEvent(const ultralight::ScrollEvent& evt) { return true; }
 };
 
 ///

Ultralight/Bitmap.h

@@ -9,7 +9,7 @@
 ///
 /// Website: <http://ultralig.ht>
 ///
-/// Copyright (C) 2021 Ultralight, Inc. All rights reserved.
+/// Copyright (C) 2022 Ultralight, Inc. All rights reserved.
 ///
 #pragma once
 #include <Ultralight/Defines.h>
@@ -18,8 +18,6 @@
 
 namespace ultralight {
 
-#pragma pack(push, 1)
-
 ///
 /// The various Bitmap formats.
 ///
@@ -48,6 +46,12 @@ enum class UExport BitmapFormat : uint8_t {
 ///
 #define GetBytesPerPixel(x) (x == BitmapFormat::A8_UNORM ? 1 : 4)
 
+///
+/// Forward declaration for the LockedPixels class.
+/// 
+template<typename T>
+class LockedPixels;
+
 ///
 /// @brief  Bitmap container with basic blitting and conversion routines.
 ///
@@ -71,6 +75,25 @@ class UExport Bitmap : public RefCounted {
   ///
   static RefPtr<Bitmap> Create(uint32_t width, uint32_t height, BitmapFormat format);
 
+  ///
+  /// Create an aligned Bitmap with a certain configuration. Pixels will be allocated but not
+  /// initialized. Row bytes will be padded to reach the specified alignment.
+  ///
+  /// @param  width   The width in pixels.
+  ///
+  /// @param  height  The height in pixels.
+  ///
+  /// @param  format  The pixel format to use.
+  ///
+  /// @param  alignment  The alignment (in bytes) to use. Row bytes will be padded to reach a
+  ///                    multiple of this value and the underlying storage will be allocated with
+  ///                    this alignment.
+  ///
+  /// @return  A ref-pointer to a new Bitmap instance.
+  ///
+  static RefPtr<Bitmap> Create(uint32_t width, uint32_t height, BitmapFormat format,
+                               uint32_t alignment);
+
   ///
   /// Create a Bitmap with existing pixels and configuration.
   ///
@@ -148,6 +171,14 @@ class UExport Bitmap : public RefCounted {
   ///
   virtual bool owns_pixels() const = 0;
 
+  ///
+  /// Lock the pixel buffer for reading/writing (safe version, automatically unlocks).
+  ///
+  /// @return  A managed container that can be used to access the pixels (LockedPixels::data()).
+  ///          This container will automatically unlock the pixels when it goes out of scope.
+  ///
+  virtual LockedPixels<RefPtr<Bitmap>> LockPixelsSafe() const = 0;
+
   ///
   /// Lock the pixel buffer for reading/writing.
   ///
@@ -213,7 +244,7 @@ class UExport Bitmap : public RefCounted {
   ///                     edge pixels from the source bitmap.
   ///
   /// @return  Whether or not the operation succeeded (this can fail if the src_rect and/or
-  ///          dest_rect are invalid, or if their total dimensions do not match).
+  ///          dest_rect are invalid).
   ///
   virtual bool DrawBitmap(IntRect src_rect, IntRect dest_rect, RefPtr<Bitmap> src, bool pad_repeat)
       = 0;
@@ -277,6 +308,62 @@ class UExport Bitmap : public RefCounted {
   void operator=(const Bitmap&);
 };
 
-#pragma pack(pop)
+template <typename T>
+class LockedPixels {
+ public:
+  LockedPixels(const LockedPixels&) = delete;
+  LockedPixels& operator=(const LockedPixels&) = delete; 
+  LockedPixels(int) = delete;
+  explicit LockedPixels(T& lockable) : lockable_(lockable), data_(nullptr), size_(0) { lock(); }
+
+  ~LockedPixels() {
+    if (lockable_)
+      lockable_->UnlockPixels();
+  }
+
+  ///
+  /// Access the locked pixel data.
+  /// 
+  void* data() { return data_; }
+
+  ///
+  /// Access the size of the locked pixel data.
+  /// 
+  size_t size() { return size_; }
+
+  explicit operator bool() const { return !!lockable_; }
+
+  LockedPixels(LockedPixels&& other) : lockable_(other.lockable_), data_(other.data_), 
+      size_(other.size_) {
+    other.lockable_ = nullptr;
+    other.data_ = nullptr;  
+    other.size_ = 0;
+  }
+
+  LockedPixels& operator=(LockedPixels&& other) {
+    if (lockable_)
+      lockable_->UnlockPixels();
+    lockable_ = other.lockable_;
+    data_ = other.data_;
+    size_ = other.size_;
+    other.lockable_ = nullptr;
+    other.data_ = nullptr;
+    other.size_ = 0;
+    return *this;
+  }
+
+ private:
+  void lock() {
+    if (lockable_) {
+      data_ = lockable_->LockPixels();
+      size_ = lockable_->size();
+    }
+  }
+
+  T lockable_;
+  void* data_;
+  size_t size_;
+};
+
 
 } // namespace ultralight

Ultralight/Buffer.h

@@ -9,26 +9,57 @@
 ///
 /// Website: <http://ultralig.ht>
 ///
-/// Copyright (C) 2021 Ultralight, Inc. All rights reserved.
+/// Copyright (C) 2022 Ultralight, Inc. All rights reserved.
 ///
 #pragma once
 #include <Ultralight/Defines.h>
 #include <Ultralight/RefPtr.h>
 
 namespace ultralight {
 
+///
+/// Function signature for a user-defined destruction callback to be optionally called when Buffer
+/// is destroyed.
+///
+/// @param  user_data  Pointer to user-defined user-data (this will be the same value as what was
+///                    passed to Buffer::Create, if any)
+///
+/// @param  data       Pointer to raw Buffer data.
+/// 
+typedef void (*DestroyBufferCallback)(void* user_data, void* data);
+
 ///
 /// A fixed-size byte container for passing data around.
 ///
 class UExport Buffer : public RefCounted {
-public:
+ public:
+  ///
+  /// Create a Buffer from existing, user-owned data without any copies. An optional, user-supplied
+  /// callback will be called to deallocate data upon destruction.
+  ///
+  /// @param  data                  A pointer to the data.
+  ///
+  /// @param  size                  Size of the data in bytes.
+  ///
+  /// @param  user_data             Optional user data that will be passed to destruction_callback
+  ///                               when the returned Buffer is destroyed.
+  ///
+  /// @param  destruction_callback  Optional callback that will be called upon destruction. Pass a
+  ///                               null pointer if you don't want to be informed of destruction.
+  ///
   ///
-  /// Create a Buffer, a copy of data is made.
+  /// @return  A ref-counted Buffer object that wraps the existing data.
   ///
-  static RefPtr<Buffer> Create(const void* data, size_t size);
+  static RefPtr<Buffer> Create(void* data, size_t size, void* user_data,
+                               DestroyBufferCallback destruction_callback);
 
   ///
-  /// Get a pointer to raw byte data.
+  /// Create a Buffer from existing data, a deep copy of data will be made.
+  ///
+  static RefPtr<Buffer> CreateFromCopy(const void* data, size_t size);
+
+  ///
+  /// Get a pointer to the raw byte data.
   ///
   virtual void* data() = 0;
 
@@ -37,11 +68,23 @@ class UExport Buffer : public RefCounted {
   ///
   virtual size_t size() const = 0;
 
-protected:
+  ///
+  /// Get the user data associated with this Buffer, if any.
+  ///
+  virtual void* user_data() = 0;
+
+  ///
+  /// Check whether this Buffer owns its own data (Buffer was created via CreateFromCopy).
+  /// If this is false, Buffer will call the user-supplied destruction callback to deallocate data
+  /// when this Buffer instance is destroyed.
+  ///
+  virtual bool owns_data() const = 0;
+
+ protected:
   Buffer();
   virtual ~Buffer();
   Buffer(const Buffer&);
   void operator=(const Buffer&);
 };
 
-}  // namespace ultralight
+} // namespace ultralight