зеркало из https://github.com/stride3d/SharpFont.git
Updated README to reflect newest info about win64 builds.
This commit is contained in:
Robert Rouhani
Родитель
f532c95359
Коммит
28aabed067
136
README.md
136
README.md
|
|
@ -2,18 +2,21 @@ SharpFont [](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 <robert.rouhani@gmail.com>
|
||||
|
||||
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
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче