From 10dae476247cc153ac27c1b56bc1587e46ca5d0e Mon Sep 17 00:00:00 2001 From: Scott Williams Date: Sun, 19 Apr 2020 12:55:09 +0100 Subject: [PATCH] Initial introduction and getting started guides for ImageSharp.Drawing and Fonts --- articles/fonts/customrendering.md | 134 + articles/fonts/gettingstarted.md | 59 + articles/fonts/index.md | 46 + articles/imagesharp.drawing/gettingstarted.md | 112 + articles/imagesharp.drawing/index.md | 48 + articles/toc.md | 23 +- docs/api/index.html | 13 +- docs/articles/ImageSharp/Configuration.html | 2 +- docs/articles/ImageSharp/GettingStarted.html | 14 +- docs/articles/ImageSharp/ImageFormats.html | 22 +- .../articles/ImageSharp/MemoryManagement.html | 12 +- docs/articles/ImageSharp/PixelFormats.html | 10 +- docs/articles/ImageSharp/Processing.html | 4 +- docs/articles/ImageSharp/Resize.html | 4 +- .../ImageSharp/WorkingWithPixelBuffers.html | 4 +- docs/articles/ImageSharp/index.html | 2 +- docs/articles/fonts/customrendering.html | 246 + docs/articles/fonts/gettingstarted.html | 165 + docs/articles/fonts/index.html | 161 + .../imagesharp.drawing/gettingstarted.html | 204 + docs/articles/imagesharp.drawing/index.html | 162 + docs/articles/intro.html | 2 +- docs/articles/toc.html | 60 +- docs/index.html | 2 +- docs/index.json | 2708 +- docs/manifest.json | 6567 +- docs/styles/docfx.css | 52 +- docs/styles/docfx.js | 20 +- docs/styles/docfx.vendor.js | 11 +- docs/toc.html | 2 +- docs/xrefmap.yml | 53879 +--------------- ext/Fonts | 2 +- ext/ImageSharp | 2 +- ext/ImageSharp.Drawing | 2 +- ext/ImageSharp.Web | 2 +- 35 files changed, 1621 insertions(+), 63137 deletions(-) create mode 100644 articles/fonts/customrendering.md create mode 100644 articles/fonts/gettingstarted.md create mode 100644 articles/fonts/index.md create mode 100644 articles/imagesharp.drawing/gettingstarted.md create mode 100644 articles/imagesharp.drawing/index.md create mode 100644 docs/articles/fonts/customrendering.html create mode 100644 docs/articles/fonts/gettingstarted.html create mode 100644 docs/articles/fonts/index.html create mode 100644 docs/articles/imagesharp.drawing/gettingstarted.html create mode 100644 docs/articles/imagesharp.drawing/index.html diff --git a/articles/fonts/customrendering.md b/articles/fonts/customrendering.md new file mode 100644 index 00000000..ed52ad7d --- /dev/null +++ b/articles/fonts/customrendering.md @@ -0,0 +1,134 @@ +# Custom Rendering + +>[!WARNING] +>Fonts is still considered BETA quality and we still reserve the rights to change the API shapes. We are yet to priorities performance in our font loading and layout APIs. + +>[!NOTE] +>ImageSharp.Drawing already implements the glyph rendering for you unless you are rendering on other platforms we would recommend using the version build into that library.. this is a more advanced topic. + +### Implementing a glyph renderer + +The abstraction used by `Fonts` to allow implementing glyph rendering is the `IGlyphRenderer` and its brother `IColoredGlypheRenderer` (for colored emoji support). + + +```c# + // `IColoredGlyphRenderer` implements `IGlyphRenderer` so if you don't want colored font support just implement `IGlyphRenderer`. +public class CustomGlyphRenderer : IColoredGlyphRenderer +{ + + /// + /// Called before any glyphs have been rendered. + /// + /// The bounds the text will be rendered at and at whats size. + void IGlyphRenderer.BeginText(FontRectangle bounds) + { + // called before any thing else to provide access to the total required size to redner the text + } + + /// + /// Begins the glyph. + /// + /// The bounds the glyph will be rendered at and at what size. + /// The set of paramaters that uniquely represents a version of a glyph in at particular font size, font family, font style and DPI. + /// Returns true if the glyph should be rendered othersie it returns false. + bool IGlyphRenderer.BeginGlyph(FontRectangle bounds, GlyphRendererParameters paramaters) + { + // called before each glyph/glyph layer is rendered. + // The paramaters can be used to detect the exact details + // of the glyph so that duplicate glyphs could optionally + // be cached to reduce processing. + + // You can return false to skip all the figures within the glyph (if you return false EndGlyph will still be called) + } + + /// + /// Sets the color to use for the current glyph. + /// + /// The color to override the renders brush with. + void IColorGlyphRenderer.SetColor(GlyphColor color) + { + // from the IColorGlyphRenderer version, onlt called if the current glyph should override the forgound color of current glyph/layer + } + + /// + /// Begins the figure. + /// + void IGlyphRenderer.BeginFigure() + { + // called at the start of the figure within the single glyph/layer + // glyphs are rendered as a serise of arcs, lines and movements + // which together describe a complex shape. + } + + /// + /// Sets a new start point to draw lines from + /// + /// The point. + void IGlyphRenderer.MoveTo(Vector2 point) + { + // move current point to location marked by point without describing a line; + } + + /// + /// Draw a quadratic bezier curve connecting the previous point to . + /// + /// The second control point. + /// The point. + void IGlyphRenderer.QuadraticBezierTo(Vector2 secondControlPoint, Vector2 point) + { + // describes Quadratic Bezier curve from the 'current point' using the + // 'second control point' and final 'point' leaving the 'current point' + // at 'point' + } + + /// + /// Draw a Cubics bezier curve connecting the previous point to . + /// + /// The second control point. + /// The third control point. + /// The point. + void IGlyphRenderer.CubicBezierTo(Vector2 secondControlPoint, Vector2 thirdControlPoint, Vector2 point) + { + // describes Cubic Bezier curve from the 'current point' using the + // 'second control point', 'third control point' and final 'point' + // leaving the 'current point' at 'point' + } + + /// + /// Draw a straight line connecting the previous point to . + /// + /// The point. + void IGlyphRenderer.LineTo(Vector2 point) + { + // describes straight line from the 'current point' to the final 'point' + // leaving the 'current point' at 'point' + } + + /// + /// Ends the figure. + /// + void IGlyphRenderer.EndFigure() + { + // Called after the figure has completed denoting a straight line should + // be drawn from the current point to the first point + } + + /// + /// Ends the glyph. + /// + void IGlyphRenderer.EndGlyph() + { + // says the all figures have completed for the current glyph/layer. + // NOTE this will be called even if BeginGlyph return false. + } + + + /// + /// Called once all glyphs have completed rendering + /// + void IGlyphRenderer.EndText() + { + //once all glyphs/layers have been drawn this is called. + } +} +``` \ No newline at end of file diff --git a/articles/fonts/gettingstarted.md b/articles/fonts/gettingstarted.md new file mode 100644 index 00000000..aeafac47 --- /dev/null +++ b/articles/fonts/gettingstarted.md @@ -0,0 +1,59 @@ +# Getting Started + +>[!WARNING] +>Fonts is still considered BETA quality and we still reserve the rights to change the API shapes. We are yet to priorities performance in our font loading and layout APIs. + +>[!NOTE] +>The official guide assumes intermediate level knowledge of C# and .NET. If you are totally new to .NET development, it might not be the best idea to jump right into a framework as your first step - grasp the basics then come back. Prior experience with other languages and frameworks helps, but is not required. + +### Fonts + +Fonts provides the core to your text layout and loading subsystems. + +- `SixLabors.Fonts.FontCollection` is the root type you will configure and load up with all the TrueType/OpenType/Woff fonts. (font loading is deemed expensive and should be done once and shared across multiple rasterizations) +- `SixLabors.Fonts.Font` is our currying type for passing information about your chosen font face. + +### Loading Fonts + +Fonts provides several options for loading fonts, you can load then from a streams or files, we also support loading collections out of *.TTC files and well as single variants out if individual *.TTF files. We also support loading *.woff files. + +#### Minimal Example + +```c# +using SixLabors.Fonts; + +FontCollection collection = new FontCollection(); +FontFamily family = collection.Install("path/to/font.ttf"); +Font font = family.Create(12, FontStyle.Italic); + +// "font" can now be used in calls to DrawText from our ImageSharp.Drawing library. + +``` + +#### Expanded Example + +```c# +using SixLabors.Fonts; + +FontCollection collection = new FontCollection(); +collection.Install("path/to/font.ttf"); +collection.Install("path/to/font2.ttf"); +collection.Install("path/to/emojiFont.ttf"); +collection.InstallCollection("path/to/font.ttc"); + +if(collection.TryFind("Font Name", out FontFamily family)) +if(collection.TryFind("Emoji Font Name", out FontFamily emojiFamily)) +{ + // family will not be null here + Font font = family.Create(12, FontStyle.Italic); + RendererOptions options = new RendererOptions(font, dpi: 72) + { + ApplyKerning = true, + FallbackFontFamilies = new [] + { + emojiFamily // will be used if a particular code point doesn't exist in the font passed into the constructor. (e.g. emoji) + } + }; + FontRectangle rect = TextMeasurer.Measure("Text to measure", options); +} +``` \ No newline at end of file diff --git a/articles/fonts/index.md b/articles/fonts/index.md new file mode 100644 index 00000000..ae002ef7 --- /dev/null +++ b/articles/fonts/index.md @@ -0,0 +1,46 @@ +# Introduction + +>[!WARNING] +>Fonts is still considered BETA quality and we still reserve the rights to change the API shapes. WE are yet to priorities performance in our drawing APIs. + +### What is Fonts? +Fonts is a font loading and layout library built primarily to provide text drawing support to ImageSharp.Drawing. + +Built against [.NET Standard 1.3](https://docs.microsoft.com/en-us/dotnet/standard/net-standard), Fonts can be used in device, cloud, and embedded/IoT scenarios. + +### License +Fonts is licensed under under the terms of [GNU Affero General +Public License, version 3](https://www.gnu.org/licenses/agpl-3.0.en.html). Commercial licensing options are available in addition to this license, see https://sixlabors.com/pricing for details. + +### Installation + +ImageSharp.Drawing is installed via [Nuget](https://www.nuget.org/packages/SixLabors.Fonts) with nightly builds available on [MyGet](https://www.myget.org/feed/sixlabors/package/nuget/SixLabors.Fonts). + +# [Package Manager](#tab/tabid-1) + +```bash +PM > Install-Package SixLabors.Fonts -Version VERSION_NUMBER +``` + +# [.NET CLI](#tab/tabid-2) + +```bash +dotnet add package SixLabors.Fonts --version VERSION_NUMBER +``` + +# [PackageReference](#tab/tabid-3) + +```xml + +``` + +# [Paket CLI](#tab/tabid-4) + +```bash +paket add SixLabors.Fonts --version VERSION_NUMBER +``` + +*** + +>[!WARNING] +>Prerelease versions installed via the [Visual Studio Nuget Package Manager](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio) require the "include prerelease" checkbox to be checked. \ No newline at end of file diff --git a/articles/imagesharp.drawing/gettingstarted.md b/articles/imagesharp.drawing/gettingstarted.md new file mode 100644 index 00000000..6ca48bf0 --- /dev/null +++ b/articles/imagesharp.drawing/gettingstarted.md @@ -0,0 +1,112 @@ +# Getting Started + +>[!WARNING] +>ImageSharp.Drawing is still considered BETA quality and we still reserve the rights to change the API shapes. WE are yet to priorities performance in our drawing APIs. + +>[!NOTE] +>The official guide assumes intermediate level knowledge of C# and .NET. If you are totally new to .NET development, it might not be the best idea to jump right into a framework as your first step - grasp the basics then come back. Prior experience with other languages and frameworks helps, but is not required. + +### ImageSharp.Drawing - Paths and Polygons + +ImageSharp.Drawing provides several classes for build and manipulating various shapes and paths. + +- @"SixLabors.ImageSharp.Drawing.IPath" Root interface defining a path/polygon and the type that the rasterizer uses to generate pixel output. +- This `SixLabors.ImageSharp.Drawing` namespace contains a variety of available polygons to speed up your drawing process. + +In addition to the vector manipulation APIs we also have the rasterization APIs that can convert your @"SixLabors.ImageSharp.Drawing.IPath"s to pixels. + +### Drawing Polygons + +ImageSharp provides several options for drawing polygons weather you want to draw outlines or fill the shapes. + +#### Minimal Example + +```c# +using SixLabors.ImageSharp; +using SixLabors.ImageSharp.Processing; +using SixLabors.ImageSharp.Drawing.Processing; + +Image image = ...; // create any way you like. + +IPath yourPolygon = new Star(x: 100.0f, y: 100.0f, prongs: 5, innerRadii: 20.0f, outerRadii:30.0f) + +image.Mutate( x=> x.Fill(Color.Red, yourPolygon)); // fill the star with red + +``` + +#### Expanded Example + +```c# +using SixLabors.ImageSharp; +using SixLabors.ImageSharp.Processing; +using SixLabors.ImageSharp.Drawing.Processing; +using SixLabors.ImageSharp.PixelFormats; + +Image image = ...; // create any way you like. + +// The options are optional +ShapeGraphicsOptions options = new ShapeGraphicsOptions() +{ + ColorBlendingMode = PixelColorBlendingMode.Multiply +}; + +IBrush brush = Brushes.Horizontal(Color.Red, Color.Blue); +IPen pen = Pens.DashDot(Color.Green, 5); +IPath yourPolygon = new Star(x: 100.0f, y: 100.0f, prongs: 5, innerRadii: 20.0f, outerRadii:30.0f) + +// draws a star with Horizontal red and blue hatching with a dash dot pattern outline. +image.Mutate( x=> x.Fill(options, brush, yourPolygon) + .Draw(option, pen, yourPolygon)); +``` + +### API Cornerstones for Polygon Rasterization +Our `Fill` APIs always work off a `Brush` (some helpers create the brush for you) and will take your provided set of paths and polygons filling in all the pixels inside the vector with the color the brush provides. + +Our `Draw` APIs always work off the `Pen` where we processes your vector to create an outline with a certain pattern and fill in the outline with an internal brush inside the pen. + + +### Drawing Text + +ImageSharp.Drawing provides several options for drawing text all overloads of a single `DrawText` API. Our text drawing infrastructure is build on top of our [Fonts](../fonts) library. (See [SixLabors.Fonts](../fonts) for details on handling fonts.) + +#### Minimal Example + +```c# +using SixLabors.ImageSharp; +using SixLabors.ImageSharp.Processing; +using SixLabors.ImageSharp.Drawing.Processing; + +Image image = ...; // create any way you like. +Font font = ...; // see our Fonts library for best practices on retriving one of these. +string yourText = "this is some sample text"; + +image.Mutate( x=> x.DrawText(yourText, font, Color.Black, new PointF(10, 10))); +``` + +#### Expanded Example + +```c# +using SixLabors.ImageSharp; +using SixLabors.ImageSharp.Processing; +using SixLabors.ImageSharp.Drawing.Processing; +using SixLabors.ImageSharp.PixelFormats; + +Image image = ...; // create any way you like. +Font font = ...; // see our Fonts library for best practices on retriving one of these. + +// The options are optional +TextGraphicsOptions options = new TextGraphicsOptions() +{ + ApplyKerning = true, + TabWidth = 8, // a tab renders as 8 spaces wide + WrapTextWidth = 100, // greater than zero so we will word wrap at 100 pixels wide + HorizontalAlignment = HorizontalAlignment.Right // right align +}; + +IBrush brush = Brushes.Horizontal(Color.Red, Color.Blue); +IPen pen = Pens.DashDot(Color.Green, 5); +string text = "sample text"; + +// draws a star with Horizontal red and blue hatching with a dash dot pattern outline. +image.Mutate( x=> x.DrawText(options, text, font, brush, pen, new PointF(100, 100)); +``` \ No newline at end of file diff --git a/articles/imagesharp.drawing/index.md b/articles/imagesharp.drawing/index.md new file mode 100644 index 00000000..4d572c1f --- /dev/null +++ b/articles/imagesharp.drawing/index.md @@ -0,0 +1,48 @@ +# Introduction + +>[!WARNING] +>ImageSharp.Drawing is still considered BETA quality and we still reserve the rights to change the API shapes. WE are yet to priorities performance in our drawing APIs. + +### What is ImageSharp.Drawing? +ImageSharp.Drawing is a library build on top on ImageSharp to providing 2D Drawing extensions on top of ImageSharp. + +ImageSharp.Drawing is designed from the ground up to be flexible and extensible. The library provides API endpoints for common vector and text processing operations adds the building blocks for building custom image. + +Built against [.NET Standard 1.3](https://docs.microsoft.com/en-us/dotnet/standard/net-standard), ImageSharp.Drawing can be used in device, cloud, and embedded/IoT scenarios. + +### License +ImageSharp.Drawing is licensed under under the terms of [GNU Affero General +Public License, version 3](https://www.gnu.org/licenses/agpl-3.0.en.html). Commercial licensing options are available in addition to this license, see https://sixlabors.com/pricing for details. + +### Installation + +ImageSharp.Drawing is installed via [Nuget](https://www.nuget.org/packages/SixLabors.ImageSharp.Drawing) with nightly builds available on [MyGet](https://www.myget.org/feed/sixlabors/package/nuget/SixLabors.ImageSharp.Drawing). + +# [Package Manager](#tab/tabid-1) + +```bash +PM > Install-Package SixLabors.ImageSharp.Drawing -Version VERSION_NUMBER +``` + +# [.NET CLI](#tab/tabid-2) + +```bash +dotnet add package SixLabors.ImageSharp.Drawing --version VERSION_NUMBER +``` + +# [PackageReference](#tab/tabid-3) + +```xml + +``` + +# [Paket CLI](#tab/tabid-4) + +```bash +paket add SixLabors.ImageSharp.Drawing --version VERSION_NUMBER +``` + +*** + +>[!WARNING] +>Prerelease versions installed via the [Visual Studio Nuget Package Manager](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio) require the "include prerelease" checkbox to be checked. \ No newline at end of file diff --git a/articles/toc.md b/articles/toc.md index 0552db76..09fe8140 100644 --- a/articles/toc.md +++ b/articles/toc.md @@ -1,9 +1,16 @@ -# [Introduction](imagesharp/index.md) -# [Getting Started](imagesharp/gettingstarted.md) -## [Pixel Formats](imagesharp/pixelformats.md) -## [Image Formats](imagesharp/imageformats.md) +# [ImageSharp](imagesharp/index.md) +## [Getting Started](imagesharp/gettingstarted.md) +### [Pixel Formats](imagesharp/pixelformats.md) +### [Image Formats](imagesharp/imageformats.md) -## [Processing Images](imagesharp/Processing.md) -## [Working with Pixel Buffers](imagesharp/WorkingWithPixelBuffers.md) -## [Configuration](imagesharp/Configuration.md) -## [Memory Management](imagesharp/MemoryManagement.md) +### [Processing Images](imagesharp/Processing.md) +### [Working with Pixel Buffers](imagesharp/WorkingWithPixelBuffers.md) +### [Configuration](imagesharp/Configuration.md) +### [Memory Management](imagesharp/MemoryManagement.md) + +# [ImageSharp.Drawing](imagesharp.drawing/index.md) +## [Getting Started](imagesharp.drawing/gettingstarted.md) + +# [Fonts](fonts/index.md) +## [Getting Started](fonts/gettingstarted.md) +## [Custom Rendering](fonts/customrendering.md) diff --git a/docs/api/index.html b/docs/api/index.html index 6091ad0d..ba52d4dc 100644 --- a/docs/api/index.html +++ b/docs/api/index.html @@ -9,7 +9,7 @@ API Documentation - + @@ -17,7 +17,7 @@ - + @@ -67,14 +67,7 @@