diff --git a/README.md b/README.md index e30835c..86de7be 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,21 @@ SharpFont [![NuGet Version](http://img.shields.io/nuget/v/SharpFont.svg)](https: ========= ### Cross-platform FreeType bindings for .NET -SharpFont is a library that provides FreeType bindings for .NET. It's MIT licensed to make sure licensing doesn't get -in the way of using the library in your own projects. Unlike -[Tao.FreeType](http://taoframework.svn.sourceforge.net/viewvc/taoframework/trunk/src/Tao.FreeType/), SharpFont provides -the full public API and not just the basic methods needed to render simple text. Everything from format-specific APIs -to the caching subsystem are included. +SharpFont is a library that provides FreeType bindings for .NET. It's MIT +licensed to make sure licensing doesn't get in the way of using the library in +your own projects. Unlike [Tao.FreeType][1], SharpFont provides the full +public API and not just the basic methods needed to render simple text. +Everything from format-specific APIs to the caching subsystem are included. SharpFont simplifies the FreeType API in a few ways: - - The error codes that most FreeType methods return are converted to exceptions. - - Since the return values are no longer error codes, methods with a single `out` parameter are returned instead. - - Most methods are instance methods instead of static methods. This avoids unnecessary redundancy in method calls and -creates an API with a .NET look-and-feel. + - The error codes that most FreeType methods return are converted to + exceptions. + - Since the return values are no longer error codes, methods with a single + `out` parameter are returned instead. + - Most methods are instance methods instead of static methods. This avoids + unnecessary redundancy in method calls and creates an API with a .NET + look-and-feel. For example, a regular FreeType method looks like this: @@ -31,47 +34,57 @@ Face face = new Face(library, "./myfont.ttf"); ##Quick Start ###NuGet -SharpFont is available on [NuGet](https://nuget.org/packages/SharpFont/). It can be installed by issuing the following -command in the package manager console: +SharpFont is available on [NuGet][2]. It can be installed by issuing the +following command in the package manager console: ``` PM> Install-Package SharpFont ``` ###From Source -Clone the repository and compile the solution. Copy `SharpFont.dll` to your project and include it as a reference. On -Windows, you must include a compiled copy of FreeType2 as `freetype6.dll` in the project's output directory. It is +Clone the repository and compile the solution. Copy `SharpFont.dll` to your +project and include it as a reference. On Windows, you must include a compiled +copy of FreeType2 as `freetype6.dll` in the project's output directory. It is possible to rename the file by changing the filename constant in -[FT.Internal.cs](SharpFont/blob/master/SharpFont/FT.Internal.cs) and recompile. On Linux and OSX (and any other -Mono-supported platform), you must also copy `SharpFont.dll.config` to the project's output directory. +[FT.Internal.cs][3] and recompile. On Linux and OSX (and any other Mono +supported platform), you must also copy `SharpFont.dll.config` to the +project's output directory. ####Mono -If compiling on the command line, `xbuild` will choose the Debug WIN64 configuration by default, which will cause -issues. Instead, run `make` to compile with the proper configuration. +With the removal of the `WIN64` configurations, the included `Makefile` is +effectively redundant. However, you can still build SharpFont by calling +`make` while in the root directory of this project. ####FreeType -A copy of `freetype6.dll` can be found in the [Dependencies](https://github.com/Robmaister/SharpFont/tree/master/Dependencies) directory. +A large number of FreeType builds for Windows are now available in the +[SharpFont.Dependencies][4] repository. ##Compiling FreeType on Windows -The included copy of `freetype6.dll` is something I build on my machine when a new version of FreeType is released. -This means that it may not work on older versions of Windows. If this is the case, you can compile FreeType yourself -from source. +The copies of `freetype6.dll` that the Examples project uses by default are +chosen based on what works on my machine, and I will probably update it as +soon as a new version of FreeType is released. This means that it may not work +on older versions of Windows. If this is the case, you can either modify +the project file to point to another included version of freetype or you can +compile FreeType yourself from source. -**Note**: Any copy of `freetype6.dll` can work as a drop-in replacement, including -[this copy](http://gnuwin32.sourceforge.net/packages/freetype.htm) from the GnuWin32 project. Older versions such as -that one may crash with a `EntryPointException` when using newer APIs. +**Note**: Any copy of `freetype6.dll` can work as a drop-in replacement, +including [this copy][5] from the GnuWin32 project. Older versions such as +that one may crash with a `EntryPointException` when using newer APIs. **If on +a 64-bit machine** not patching the source code will cause SharpFont to crash +in weird places. -Thanks to [this StackOverflow answer](http://stackoverflow.com/a/7387618/1122135) for the directions: +Thanks to [this StackOverflow answer][6] for the directions: - 1. Download the latest [FreeType source code](http://sourceforge.net/projects/freetype/files/freetype2/). - 2. Open `builds\win32\vc2010\freetype.sln` (or whatever version of Visual Studio you have) in Visual Studio. + 1. Download the latest [FreeType source code][7]. + 2. Open `builds\win32\vc2010\freetype.sln` (or whatever version of Visual + Studio you have) in Visual Studio. 3. Change the compile configuration from Debug to Release. 4. Open the project properties window through Project -> Properties. - 5. In the `General` selection, change the `Target Name` to `freetype6` and the `Configuration Type` to `Dynamic -Library (.dll)`. - 6. Open up `ftoption.h` (in the project's `Header Files` section) and add the following three lines near the `DLL -export compilation` section: + 5. In the `General` selection, change the `Target Name` to `freetype6` and + the `Configuration Type` to `Dynamic Library (.dll)`. + 6. Open up `ftoption.h` (in the project's `Header Files` section) and add the + following three lines near the `DLL export compilation` section: ```C #define FT_EXPORT(x) __declspec(dllexport) x @@ -79,43 +92,40 @@ export compilation` section: #define FT_BASE(x) __declspec(dllexport) x ``` -Finally, complile the project (`F6` or Build -> Build Solution). `freetype6.dll` will be output to `objs\win32\vc2010`. + 7. **If compiling for 64-bit** apply a patch to the source code (see + [Known Issues](#Known Issues)). + 8. **Also only for 64-bit** open up Configuration Manager (the last option in + the dropdown menu when changing your compile configuration) and change + `Platform` to `x64`. + +Finally, complile the project (`F6` or Build -> Build Solution). +`freetype6.dll` will be output to `objs\win32\vc2010`. If this is a build that +isn't included in [Dependencies][4], consider forking and submitting a pull +request with your new build. ##Known Issues -The biggest currently known issue is the Windows 64-bit incompatibility. This is a three part issue: +The biggest currently known issue is the Windows 64-bit incompatibility. A +patch must be applied to FreeType before it will work properly with SharpFont. - - Windows uses the LLP64 data model while most other operating systems (including Linux and OSX) use the LP64 data -model. This means that on Windows, only `long long`s and pointers are 64 bits long and everything else remains 32 bits -long. On LP64 systems, `long`s are also 64 bits long. This creates a discrepancy between the length of the `long` type -on different operating systems. - - FreeType makes heavy use of the `long` type, specifically their `FT_Long`, `FT_ULong`, `FT_Fixed`, `FT_Pos`, and -`FT_F26Dot6` typedefs. This makes the size of FreeType structs different on Windows 64-bit systems and other 64-bit -systems. - - The C# `long` type is always 64 bits long, which doesn't always match the length of the native `long` type. For all -LP64 systems, the `IntPtr` type works because it's length matches the length of a pointer on that system. For LLP64 -systems, this doesn't work because `long` is 32 bits long while a pointer is 64 bits long. - -The simplest solution is to compile your project as x86 because all systems will default on the 32 bit FreeType binary. -However, this can be restrictive to some applications. The best solution is to compile a version of FreeType with -64-bit `long`s, which I will look into and test in the near future. +TODO: make a .patch file ##License -As metioned earlier, SharpFont is licensed under the MIT License. The terms of the MIT license are included in both the -[LICENSE](SharpFont/blob/master/LICENSE) file and below: +As metioned earlier, SharpFont is licensed under the MIT License. The terms of +the MIT license are included in both the [LICENSE][8] file and below: ``` Copyright (c) 2012-2013 Robert Rouhani SharpFont based on Tao.FreeType, Copyright (c) 2003-2007 Tao Framework Team -Permission is hereby granted, free of charge, to any person obtaining a copy of -this software and associated documentation files (the "Software"), to deal in -the Software without restriction, including without limitation the rights to -use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies -of the Software, and to permit persons to whom the Software is furnished to do -so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. @@ -129,10 +139,20 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` -The Windows binary of FreeType that is included in the Examples project and in the NuGet package is redistributed under -the FreeType License (FTL). +The Windows binary of FreeType that is included in the Examples project and in +the NuGet package is redistributed under the FreeType License (FTL). ``` -Portions of this software are copyright (c) 2013 The FreeType Project +Portions of this software are copyright (c) 2015 The FreeType Project (www.freetype.org). All rights reserved. ``` + + +[1]: http://taoframework.svn.sourceforge.net/viewvc/taoframework/trunk/src/Tao.FreeType/ +[2]: https://nuget.org/packages/SharpFont/ +[3]: SharpFont/FT.Internal.cs +[4]: https://github.com/Robmaister/SharpFont.Dependencies +[5]: http://gnuwin32.sourceforge.net/packages/freetype.htm +[6]: http://stackoverflow.com/a/7387618/1122135 +[7]: http://sourceforge.net/projects/freetype/files/freetype2/ +[8]: LICENSE