Difference between revisions of "Mac OS X Porting - Native Fonts"

Public Documentation License Notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at http://www.openoffice.org/licenses/PDL.html. The Original Documentation is "Fonts starting point and documentation". The Initial Writer of the Original Documentation is (JCA) Eric Bachard (C) 2006. All Rights Reserved. (Initial Writer contact(s): ericb@openoffice.org.)

Native fonts implementation

Introduction

Currently, OpenOffice.org on Mac OS X does not use directly Apple system fonts, but extracts .ttf part ot (most of) them, and uses X11 rendering to display them properly.

The pro to use X11 rendering is it is faster than use Apple font server, but the drawback is all featured improvement are not accessible, in particular kerning and hinting.

Note : Apple owns a Patent who does not allow us to use kerning and hinting as expected e.g. using Freetype 
( see :http://www.freetype.org/patents.html), so workaround or other hacks must be used.

First contact with Herbert Duerr (hdu), about fonts :

Choosen answers to start :

"...I already started an ATSUI port long ago. See issue 23283 for details (http://www.openoffice.org/issues/show_bug.cgi?id=23283). This patch is very old and worked for some simple situations..."

"..Everything is in VCL, especially the vcl/inc/sallayout.hxx header file is important. vcl/*/gdi/ subdirectories might be interesting too.

The SalLayout base class is the core of all VCL-text. It corresponds to an ATSUTextLayout object on ATSUI. All text display, measurements, text breaking, glyph fallback etc. are done via SalLayout objects.."

"..I think the best way is to deeply understand a SalLayout object is to get to know the very old VCL OutputDevice text related methods, and especially what the pDXArray parameter in them means. Then learn ATSUI, Uniscribe, ICU's layout engine and Java's TextLayout really well. A SalLayout is just the abstracted combination of all these layout engines. A SalLayout object has the "old pDXArray flavour" to keep the changes required by the rest of OOo minimal.."

"..Well, changing anything in the VCL text core is very hard, because it impacts basically everything text related in OOo. Since a simple change there can easily break some use cases, several scripts, platforms and may have a bad performance impact, I'd rather not change anything in the core...

"...If it is possible to isolate it to just the file salatslayout.cxx provided in issue 23283 then I'm all for it.."

Fixme : documentation starting point :

interesting documents about design of fonts implementations in OpenOffice.org  :

[FIXME]Verify if not obsolete Font management concept : http://gsl.openoffice.org/files/documents/16/1603/vcl_new_fontmanagement.pdf

window class hierarchy :

http://gsl.openoffice.org/files/documents/16/974/VCLClassHierarchyWindows.sxd

Little glossary

Impl prefix means "Implementation detail", and such variable, functions ...etc will only be visible locally

ATS : Apple Type Services. This server works if an only if a CFRunLoop( ) is running, and launched in main thread.

ATSUI : Apple Type Services for Unicode Imagery

Sal : System Abstraction Layer

Layout (for text layout) : Text Layout contains one ore more paragraphs of text together with style attributes that may apply to character,

lines or even the entire layout. The text layout contains informations about lines and layout attributes, including justification, rotation, etc

CarretPosition: Caret is the name for the symbol ^

Point: [FIXME]

Glyph: A Glyph represents the shape of a symbol. E.g. the glyph for the character "capital latin letter O" typically looks like a hollow ellipse.

Style: One of the three traditional design features of a typeface along with size and weight - styles are either regular, italic or condensed

Offset: in our context, a number indicating the distance (displacement) from the start of a data structure object and up to a given element

Boundary: A border that encloses a space or area

GIA: Glyph Information Array

Character style information: is contained in a style object associated ( not contained by ! ) a text layout object.

You can complete with the excellent glossary Herbert Duerr provided : http://gsl.openoffice.org/files/documents/16/1890/OOo_Glossary_Of_Font_Terms.htm

Work in progress

salatslayout.cxx License origin is justified here : http://qa.openoffice.org/issues/show_bug.cgi?id=23283]

OpenOffice.org side :

1) Headers

1.1) vcl/inc/salgdi.hxx, including definition of :
SalGraphics class 

1.2) vcl/inc/sallayout.hxx, including definitions of :
classes :
ImplLayoutRuns
ImplLayoutArgs
SalLayout
MultiSalLayout (inherits of SalLayout)
GenericSalLayout

structures: 
struct GlyphItem


1.3) vcl/aqua/inc/salgdi.h, including definitions of 
 
classes : 
ImplMacFontData (inherits of ImplFontData)

AquaSalGraphics (inherits of SalGraphics, does have ATSLayout as friend class)

2) Implementation

2.1) vcl/aqua/source/inc/salatslayout.cxx

Implements the classes :
 
ATSLayout (inherits of SalLayout)

existing ATSLayout methods are :
bool ATSLayout::LayoutText()
void ATSLayout::AdjustLayout()
void ATSLayout::DrawText()
int ATSLayout::GetNextGlyphs()
long ATSLayout::GetTextWidth()
long ATSLayout::FillDXArray()
int ATSLayout::GetTextBreak()
void ATSLayout::GetCaretPositions()
bool ATSLayout::GetBoundRect() 
bool ATSLayout::InitGIA()

Other class : PolyArgs, implementing :
void PolyArgs::Init()
void PolyArgs::AddPoint()
void PolyArgs::ClosePolygon()
OSStatus MyATSCubicMoveToCallback()
OSStatus MyATSCubicLineToCallback()
OSStatus MyATSCubicCurveToCallback()
OSStatus MyATSCubicClosePathCallback ()

Mac OS X API side:

Carbon API implementation (binding) is made in salatslayout.cxx

ATS and ATSUI starting point : http://developer.apple.com/documentation/Carbon/Conceptual/ATS_Concepts/atsfonts_intro/chapter_1_section_1.html

Apple's starting page leading to deeper docs: http://developer.apple.com/documentation/TextFonts/Typography-date.html

Todo-list for native font implementation :

- missing methods (to be implemented) :

bool ATSLayout::GetGlyphOutlines()
ATSLayout::InitFont()
ATSLayout::MoveGlyph()
ATSLayout::DropGlyph()
ATSLayout::Simplify( )

- Fix known bugs :
   MultiLine does not work (writer cannot be used, because)
   Bad keyboard/charset ? (missig chars)
   When redrawing, everything is redrawn using the most little font size -> even the dialog boxes on menu bars
   Bad values returned 

- Implement MultiSalLayout
- Complete implementation   
- read Apple API [ Work in progress]
- describe current implementation : organisation / design [work in progress]
- design of new implementation [FIXME] find examples

Estimation of code remaining to write ~40 %

Done ( mainly Stephan Schaefer, with initial salatslayout.cxx file written by Herbert Duerr)

0.4

- adapt salatslayout.cxx to make it match with sallayout.hxx, and salgdi.hxx, saldata.hxx .etc 
to make it build with aquavlcl01, and do some tests :
- verify this server can be initialized inside OpenOffice.org (needs a CFRunLoop working to be correctly initialized )
- run it and fix instant crashs and verity there is no freeze

0.3

- fix compilations issues
- rewrite complete salatslayout.cxx
- verify salatsfontutils.cxx definition does match with new salatslayout.cxx content
- define correct naming convention
- replace old SalGraphicsData object implementation (found in pre-aquavcl01 files, and now obsolete, because we won't use QDraw anymore)
- understand current font implementation  ( using old salatslayout.cxx )  ( work in progress )
- analyse and describe Carbon binding in salatslayout.cxx [ 90% done]

Resources : use sample code to test/initialize ATS server ( using e.g. ATSUIDirectAccessDemo )

SalLayout base class description

[FIXME]

salatslayout.cxx description

interesting functions in Carbon/ATSUI API

ATSCreateFontQueryRunLoopSource

ATSCreateFontQueryRunLoopSource : Sets up your application to handle font queries

CFRunLoopSourceRef ATSCreateFontQueryRunLoopSource (
  CFIndex queryOrder,
  CFIndex sourceOrder,
  ATSFontQueryCallback callout,
  const ATSFontQuerySourceContext * context,
);

More Infos on CFRunLoopSourceRef

ATSUCaret

ATSUCaret

Contains the coordinates needed to draw a caret.

struct ATSUCaret {
  Fixed fX; 
  Fixed fY; 
  Fixed fDeltaX; 
  Fixed fDeltaY;
};

More infos on ATSUCaret

deprecated functions in Carbon API

ATSUCreateTextLayoutWithTextHandle  
ATSUSetTextHandleLocation   
ATSUSetFontFallbacks   
ATSUGetFontFallbacks  
ATSUFONDtoFontID  
ATSUFontIDtoFOND  
ATSUGetGlyphInfo  [done]
ATSUDrawGlyphInfo  
ATSUIdle  

Content description : salatslayout.cxx

URL's & important LINKS

sallayout.hxx description

See : http://wiki.services.openoffice.org/wiki/Sallayout.hxx

Unicode references in Wikipedia

English reference : http://en.wikipedia.org/wiki/Unicode

French reference : http://fr.wikipedia.org/wiki/Unicode

ICU references in Wikipedia

English reference : http://en.wikipedia.org/wiki/International_Components_for_Unicode

French reference : http://fr.wikipedia.org/wiki/International_Components_for_Unicode

Apple documentation

ATS and ATSUI starting point : http://developer.apple.com/documentation/Carbon/Conceptual/ATS_Concepts/atsfonts_intro/chapter_1_section_1.html Apple's starting page leading to deeper docs: http://developer.apple.com/documentation/TextFonts/Typography-date.html

New Font Management

[FIXME]

See Herbert's Duerr document : http://www.openoffice.org/files/documents/16/1603/vcl_new_fontmanagement.pdf

Mac OS X port on the wiki

1. Build Aqua version of OpenOffice.org http://wiki.services.openoffice.org/wiki/AquaBuild
2. Pierre de Filippis Wiki http://wiki.services.openoffice.org/wiki/Pdefilippis:_Project_Page
3. Christian Lippka wiki : http://wiki.services.openoffice.org/wiki/User:CL
4. Mac OS X port Meetings : http://wiki.services.openoffice.org/wiki/MacOSXPortMeetings

This work is part of http://wiki.services.openoffice.org/wiki/Mac_OS_X_Porting_-_Work_Areas/Todo%27s

Ericb 10:36, 3 September 2006 (CEST)