Update headers for 1.2.0-beta.2

adamjs · adamjs · commit c0a444be35f3 · 2020-08-12T09:56:16.000-05:00
diff --git a/AppCore/JSHelpers.h b/AppCore/JSHelpers.h
@@ -6,17 +6,14 @@
 #include <functional>
 #include <memory>
 
-///
-/// This is a simple C++ wrapper for JavaScriptCore.
-///
 namespace ultralight {
 
 ///
 /// Set the current JSContext.
 ///
 /// Most JavaScriptCore C API calls require an active JavaScript execution
 /// context (JSContextRef). You can get the JSContextRef for a page via
-/// `View::js_context()`. This context changes with each page navigation.
+/// `View::LockJSContext()`. This context changes with each page navigation.
 ///
 /// **Note**:
 ///    You MUST set a JSContext before using most of the C++ API below.
diff --git a/JavaScriptCore/JSRetainPtr.h b/JavaScriptCore/JSRetainPtr.h
@@ -32,6 +32,10 @@
 #include <JavaScriptCore/JSStringRef.h>
 #include <algorithm>
 
+#if !defined(WARN_UNUSED_RETURN)
+#define WARN_UNUSED_RETURN
+#endif
+
 inline void JSRetain(JSStringRef string) { JSStringRetain(string); }
 inline void JSRelease(JSStringRef string) { JSStringRelease(string); }
 inline void JSRetain(JSGlobalContextRef context) { JSGlobalContextRetain(context); }
diff --git a/Ultralight/Defines.h b/Ultralight/Defines.h
@@ -78,17 +78,17 @@ UExport uint32_t UltralightVersionPatch();
 ///
 /// Hi there, welcome to the C++ API Reference for Ultralight!
 ///
-/// Ultralight is a fast, lightweight HTML UI engine for desktop apps.
+/// Ultralight is a fast, lightweight HTML UI engine for desktop apps and games.
 ///
 /// If this is your first time exploring the API, we recommend
 /// starting with ultralight::Renderer and ultralight::View.
 ///
 ///
 /// @section usefullinks_sec Useful Links
-/// - Home:   <https://ultralig.ht> -- Get the latest binaries
-/// - Docs:   <https://docs.ultralig.ht> -- API overview, code snippets, tutorials and more!
-/// - Slack:  <http://chat.ultralig.ht/> -- Stuck? Have questions? Come chat with us!
-/// - GitHub: <https://github.com/ultralight-ux/ultralight> -- Report issues and browse code
+/// - Home:     <https://ultralig.ht> -- Get the latest binaries
+/// - Docs:     <https://docs.ultralig.ht> -- API overview, code snippets, tutorials and more!
+/// - Discord:  <http://chat.ultralig.ht/> -- Stuck? Have questions? Come chat with us!
+/// - GitHub:   <https://github.com/ultralight-ux/ultralight> -- Report issues and browse code
 ///
 /// @section copyright_sec Copyright
 /// Documentation is Copyright (C) 2020 Ultralight, Inc. All rights reserved.
diff --git a/Ultralight/MouseEvent.h b/Ultralight/MouseEvent.h
@@ -27,19 +27,19 @@ class MouseEvent {
   /// The various MouseEvent types.
   ///
   enum Type {
-	///
+	  ///
     /// Mouse moved type
-	///
+	  ///
     kType_MouseMoved,
 
-	///
+	  ///
     /// Mouse button pressed type
-	///
+	  ///
     kType_MouseDown,
 
-	///
+	  ///
     /// Mouse button released type
-	///
+	  ///
     kType_MouseUp,
   };
 
diff --git a/Ultralight/RenderTarget.h b/Ultralight/RenderTarget.h
@@ -24,9 +24,9 @@ namespace ultralight {
 /// @brief  Rendering details for a View, to be used with your own GPUDriver
 ///
 /// When using your own GPUDriver, each View is rendered to an offscreen
-/// texture that you must display on a quad in your engine. This struct
-/// provides all the details you need to render the View texture in your
-/// engine.
+/// texture that you can display on a 3D quad in your application. This struct
+/// provides all the details you need to display the corresponding texture in
+/// your application.
 ///
 struct UExport RenderTarget {
   ///
diff --git a/Ultralight/Renderer.h b/Ultralight/Renderer.h
@@ -20,11 +20,8 @@
 namespace ultralight {
 
 ///
-/// @brief  The core of Ultralight. You should initialize it after setting up
-///         your Platform config and drivers.
-///
-/// This singleton class manages the lifetime of all Views (@see View) and
-/// coordinates all painting, rendering, network requests, and event dispatch.
+/// @brief  This singleton manages the lifetime of all Views (@see View) and
+///         coordinates painting, network requests, and event dispatch.
 ///
 /// @note  You don't have to create this instance directly if you use the
 ///        AppCore API. The App class will automatically create a Renderer and
@@ -39,18 +36,17 @@ class UExport Renderer : public RefCounted {
   /// and allows you to manage your own runloop and painting. This method is
   /// recommended for those wishing to integrate the library into a game.
   ///
-  /// You should set up all your Platform config, file-system, font loader,
-  /// and drivers before calling this function. (@see <Ultralight/Platform.h>)
+  /// You should set up your Platform config, file-system, font loader, 
+  /// and surface-factories/gpu-drivers before calling this function. 
+  /// (@see <Ultralight/Platform.h>)
   ///
   /// At a minimum, you will need to define a FontLoader ahead of time or this
   /// call will fail. You can use the platform's native FontLoader by calling:
   /// <pre>
+  ///   /// This function is defined in <AppCore/Platform.h>
   ///   Platform::instance().set_font_loader(GetPlatformFontLoader());
   /// </pre>
   ///
-  /// @note GetPlatformFontLoader() and other native platform handlers are
-  ///       are defined in <AppCore/Platform.h>.
-  ///
   /// @note  You should only create one Renderer per application lifetime.
   ///
   /// @note: You should not call this if you are using App::Create(), it
@@ -112,13 +108,13 @@ class UExport Renderer : public RefCounted {
   virtual void Update() = 0;
 
   ///
-  /// Render all active views to their respective surfaces (or if the GPU
-  /// renderer is enabled, this will render all views to display lists and
-  /// dispatch calls to GPUDriver).
+  /// Render all active views to their respective render-targets/surfaces.
   ///
   /// You should call this once per frame (usually in synchrony with the
   /// monitor's refresh rate).
   ///
+  /// @note  Views are only repainted if they actually need painting.
+  ///
   virtual void Render() = 0;
 
   ///
@@ -128,7 +124,8 @@ class UExport Renderer : public RefCounted {
   virtual void PurgeMemory() = 0;
 
   ///
-  /// Print detailed memory usage statistics to the log. (@see Platform::set_logger())
+  /// Print detailed memory usage statistics to the log.
+  /// (@see Platform::set_logger())
   ///
   virtual void LogMemoryUsage() = 0;
 
diff --git a/Ultralight/Ultralight.h b/Ultralight/Ultralight.h
@@ -2,12 +2,14 @@
 #pragma once
 #include <Ultralight/Defines.h>
 #include <Ultralight/RefPtr.h>
-#include <Ultralight/String16.h>
 #include <Ultralight/String8.h>
+#include <Ultralight/String16.h>
+#include <Ultralight/String32.h>
 #include <Ultralight/String.h>
 #include <Ultralight/Bitmap.h>
 #include <Ultralight/Buffer.h>
 #include <Ultralight/View.h>
+#include <Ultralight/Session.h>
 #include <Ultralight/KeyCodes.h>
 #include <Ultralight/KeyEvent.h>
 #include <Ultralight/Listener.h>
@@ -22,3 +24,6 @@
 #include <Ultralight/platform/GPUDriver.h>
 #include <Ultralight/platform/FileSystem.h>
 #include <Ultralight/platform/FontLoader.h>
+#include <Ultralight/platform/Surface.h>
+#include <Ultralight/platform/Clipboard.h>
+#include <Ultralight/platform/Logger.h>
diff --git a/Ultralight/View.h b/Ultralight/View.h
@@ -26,11 +26,25 @@
 namespace ultralight {
 
 ///
-/// @brief A View is similar to a tab in a browser-- you load web content into
-///	       it and display it however you want. @see Renderer::CreateView
+/// @brief The View class is used to load and display web content.
 ///
-/// @note  The API is currently not thread-safe, all calls must be made on the
-///        main thread.
+/// View is an offscreen web-page container that can be used to display
+/// web-content in your application.
+///
+/// You can load content into a View via View::LoadURL() or View::LoadHTML()
+/// and interact with it via View::FireMouseEvent() and similar API.
+///
+/// When displaying a View, the API is different depending on whether you
+/// are using the CPU renderer or the GPU renderer:
+///
+/// When using the CPU renderer, you would get the underlying pixel-buffer
+/// surface for a View via View::surface().
+///
+/// When using the GPU renderer, you would get the underlying render target
+/// and texture information via View::render_target().
+///
+/// @note  The API is not currently thread-safe, all calls must be made on the
+///        same thread that the Renderer/App was created on.
 ///
 class UExport View : public RefCounted {
 public:
@@ -60,7 +74,7 @@ class UExport View : public RefCounted {
   virtual bool is_loading() = 0;
 
   ///
-  /// Get the RenderTarget for the View.
+  /// Get the offscreen RenderTarget for the View.
   ///
   /// @note  Only valid when the GPU renderer is enabled in Config.
   ///
@@ -70,11 +84,10 @@ class UExport View : public RefCounted {
   virtual RenderTarget render_target() = 0;
 
   ///
-  /// Get the Surface for the View (native pixel buffer container).
-  ///
-  /// @note  Only valid when the GPU renderer is disabled in Config.
+  /// Get the offscreen Surface for the View (pixel-buffer container).
   ///
-  ///        (Will return a nullptr when the GPU renderer is enabled.)
+  /// @note  Only valid when the CPU is enabled (will return a nullptr
+  ///        otherwise)
   ///
   ///        The default Surface is BitmapSurface but you can provide your
   ///        own Surface implementation via Platform::set_surface_factory.
diff --git a/Ultralight/platform/Clipboard.h b/Ultralight/platform/Clipboard.h
@@ -22,8 +22,11 @@ namespace ultralight {
 ///          
 /// This is used for reading and writing data to the platform Clipboard.
 ///
-/// This is intended to be implemented by users and defined before creating the
-/// Renderer. @see Platform::set_clipboard.
+/// AppCore automatically provides a platform-specific implementation of this
+/// that cuts/copies/pastes to the OS clipboard when you call App::Create().
+///
+/// If you are using Renderer::Create() instead, you will need to provide your
+/// own implementation of this. @see Platform::set_clipboard().
 ///
 class UExport Clipboard {
 public:
diff --git a/Ultralight/platform/Config.h b/Ultralight/platform/Config.h
@@ -18,7 +18,8 @@
 namespace ultralight {
 
 ///
-/// The winding order for front-facing triangles.
+/// The winding order for front-facing triangles. (This is only used when the
+/// GPU renderer is enabled)
 ///
 /// @note  In most 3D engines, there is the concept that triangles have a
 ///        a "front" and a "back". All the front-facing triangles (eg, those
diff --git a/Ultralight/platform/FileSystem.h b/Ultralight/platform/FileSystem.h
@@ -34,11 +34,24 @@ const FileHandle invalidFileHandle = (FileHandle)-1;
 ///
 /// @brief  FileSystem interface.
 ///          
-/// This is used for loading File URLs (eg, <file:///page.html>). If you don't
-/// implement this interface, you will not be able to load any File URLs.
+/// This is used for loading File URLs (eg, <file:///page.html>).
 ///
-/// This is intended to be implemented by users and defined before creating the
-/// Renderer. @see Platform::set_file_system.
+/// You can provide the library with your own FileSystem implementation so that
+/// file assets are loaded from your own pipeline (useful if you would like
+/// to encrypt/compress your file assets or ship it in a custom format).
+///
+/// AppCore automatically provides a platform-specific implementation of this
+/// that loads files from a local directory when you call App::Create().
+///
+/// If you are using Renderer::Create() instead, you will need to provide your
+/// own implementation via `Platform::instance().set_file_system(). For
+/// convenience, you can still use AppCore's file system implementation--
+/// see the helper functions defined in <AppCore/Platform.h>.
+///
+/// To provide your own custom FileSystem implementation, you should inherit
+/// from this class, handle the virtual member functions, and then pass an
+/// instance of your class to `Platform::instance().set_file_system()` before
+/// calling Renderer::Create() or App::Create().
 ///
 class UExport FileSystem {
 public:
diff --git a/Ultralight/platform/FontLoader.h b/Ultralight/platform/FontLoader.h
@@ -67,10 +67,20 @@ class UExport FontFile : public RefCounted {
 ///
 /// Every operating system has its own library of installed system fonts. The
 /// FontLoader interface is used to lookup these fonts and fetch the actual
-/// font data (raw TTF/OTF file data) given a certain font description.
+/// font data (raw TTF/OTF file data) for a given a certain font description.
 ///
-/// This is intended to be implemented by users and defined before creating the
-/// Renderer. @see Platform::set_font_loader
+/// AppCore automatically provides a platform-specific implementation of this
+/// that loads installed fonts from the OS when you call App::Create().
+///
+/// If you are using Renderer::Create() instead, you will need to provide your
+/// own implementation via `Platform::instance().set_font_loader(). For
+/// convenience, you can still use AppCore's font loader implementation--
+/// see the helper functions defined in <AppCore/Platform.h>.
+///
+/// To provide your own custom FontLoader implementation, you should inherit
+/// from this class, handle the virtual member functions, and then pass an
+/// instance of your class to `Platform::instance().set_font_loader()` before
+/// calling Renderer::Create() or App::Create().
 ///
 class UExport FontLoader {
 public:
diff --git a/Ultralight/platform/GPUDriver.h b/Ultralight/platform/GPUDriver.h
@@ -192,8 +192,12 @@ struct UExport CommandList {
 ///
 /// @brief  GPUDriver interface, dispatches GPU calls to the native driver.
 ///
-/// This is intended to be implemented by users and defined before creating the
-/// Renderer. @see Platform::set_gpu_driver
+/// This is automatically provided for you when you use App::Create(), AppCore
+/// provides platform-specific implementations of GPUDriver for each OS.
+///
+/// If you are using Renderer::Create(), you will need to provide your own
+/// implementation of this class if you have enabled the GPU renderer in the
+/// Config. @see Platform::set_gpu_driver
 ///
 class UExport GPUDriver {
 public:
diff --git a/Ultralight/platform/Surface.h b/Ultralight/platform/Surface.h
@@ -22,15 +22,22 @@ namespace ultralight {
 ///
 /// Offscreen pixel buffer surface. (Premultiplied BGRA 32-bit format)
 ///
-/// Each View is rendered to a Surface (@see View::surface) when the GPU
-/// renderer is disabled (the default).
+/// When using the CPU renderer, each View is painted to its own Surface.
 ///
-/// The default Surface implementation is BitmapSurface, you can retrieve the
-/// underlying bitmap via BitmapSurface::bitmap.
+/// You can provide your own Surface implementation to make the renderer
+/// paint directly to a block of memory controlled by you (this is useful for
+/// lower-latency uploads to GPU memory or other platform-specific bitmaps).
 ///
-/// You can also provide your own Surface implementation via SurfaceFactory.
-/// This can be used to wrap a platform-specific GPU texture, Windows DIB,
-/// macOS CGImage, or any other pixel buffer target for display on screen.
+/// A default Surface implementation, BitmapSurface, is automatically
+/// provided by the library when you call Renderer::Create() without defining
+/// a custom SurfaceFactory.
+///
+/// To provide your own custom Surface implementation, you should inherit
+/// from this class, handle the virtual member functions, and then define a
+/// custom SurfaceFactory that creates/destroys an instance of your class.
+/// After that, you should pass an instance of your custom SurfaceFactory class
+/// to `Platform::instance().set_font_loader()` before calling App::Create()
+/// or Renderer::Create().
 ///
 class UExport Surface {
 public:
@@ -176,7 +183,8 @@ class UExport BitmapSurface : public Surface {
 };
 
 ///
-/// Get the default Bitmap Surface Factory singleton. (Do not destroy this, owned by the library).
+/// Get the default Bitmap Surface Factory singleton. (Do not destroy this,
+/// this singleton is owned by the library).
 ///
 UExport SurfaceFactory* GetBitmapSurfaceFactory();
 
diff --git a/Ultralight/private/PlatformFileSystem.h b/Ultralight/private/PlatformFileSystem.h
