Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/graphite2/Segment.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
1 /* GRAPHITE2 LICENSING
2
3 Copyright 2010, SIL International
4 All rights reserved.
5
6 This library is free software; you can redistribute it and/or modify
7 it under the terms of the GNU Lesser General Public License as published
8 by the Free Software Foundation; either version 2.1 of License, or
9 (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
15
16 You should also have received a copy of the GNU Lesser General Public
17 License along with this library in the file named "LICENSE".
18 If not, write to the Free Software Foundation, 51 Franklin Street,
19 Suite 500, Boston, MA 02110-1335, USA or visit their web page on the
20 internet at http://www.fsf.org/licenses/lgpl.html.
21
22 Alternatively, the contents of this file may be used under the terms
23 of the Mozilla Public License (http://mozilla.org/MPL) or the GNU
24 General Public License, as published by the Free Software Foundation,
25 either version 2 of the License or (at your option) any later version.
26 */
27 #pragma once
28
29 #include "graphite2/Types.h"
30 #include "graphite2/Font.h"
31
32 #ifdef __cplusplus
33 extern "C"
34 {
35 #endif
36
37 enum gr_break_weight {
38 gr_breakNone = 0,
39 /* after break weights */
40 gr_breakWhitespace = 10,
41 gr_breakWord = 15,
42 gr_breakIntra = 20,
43 gr_breakLetter = 30,
44 gr_breakClip = 40,
45 /* before break weights */
46 gr_breakBeforeWhitespace = -10,
47 gr_breakBeforeWord = -15,
48 gr_breakBeforeIntra = -20,
49 gr_breakBeforeLetter = -30,
50 gr_breakBeforeClip = -40
51 };
52
53 enum gr_justFlags {
54 /// Indicates that this segment is a complete line
55 gr_justCompleteLine = 0,
56 /// Indicates that the start of the slot list is not at the start of a line
57 gr_justStartInline = 1,
58 /// Indicates that the end of the slot list is not at the end of a line
59 gr_justEndInline = 2
60 };
61
62 /** Used for looking up slot attributes. Most are already available in other functions **/
63 enum gr_attrCode {
64 /// adjusted glyph advance in x direction in design units
65 gr_slatAdvX = 0,
66 /// adjusted glyph advance in y direction (usually 0) in design units
67 gr_slatAdvY,
68 /// returns 0. Deprecated.
69 gr_slatAttTo,
70 /// This slot attaches to its parent at the given design units in the x direction
71 gr_slatAttX,
72 /// This slot attaches to its parent at the given design units in the y direction
73 gr_slatAttY,
74 /// This slot attaches to its parent at the given glyph point (not implemented)
75 gr_slatAttGpt,
76 /// x-direction adjustment from the given glyph point (not implemented)
77 gr_slatAttXOff,
78 /// y-direction adjustment from the given glyph point (not implemented)
79 gr_slatAttYOff,
80 /// Where on this glyph should align with the attachment point on the parent glyph in the x-direction.
81 gr_slatAttWithX,
82 /// Where on this glyph should align with the attachment point on the parent glyph in the y-direction
83 gr_slatAttWithY,
84 /// Which glyph point on this glyph should align with the attachment point on the parent glyph (not implemented).
85 gr_slatWithGpt,
86 /// Adjustment to gr_slatWithGpt in x-direction (not implemented)
87 gr_slatAttWithXOff,
88 /// Adjustment to gr_slatWithGpt in y-direction (not implemented)
89 gr_slatAttWithYOff,
90 /// Attach at given nesting level (not implemented)
91 gr_slatAttLevel,
92 /// Line break breakweight for this glyph
93 gr_slatBreak,
94 /// Ligature component reference (not implemented)
95 gr_slatCompRef,
96 /// bidi directionality of this glyph (not implemented)
97 gr_slatDir,
98 /// Whether insertion is allowed before this glyph
99 gr_slatInsert,
100 /// Final positioned position of this glyph relative to its parent in x-direction in pixels
101 gr_slatPosX,
102 /// Final positioned position of this glyph relative to its parent in y-direction in pixels
103 gr_slatPosY,
104 /// Amount to shift glyph by in x-direction design units
105 gr_slatShiftX,
106 /// Amount to shift glyph by in y-direction design units
107 gr_slatShiftY,
108 /// attribute user1
109 gr_slatUserDefnV1,
110 /// not implemented
111 gr_slatMeasureSol,
112 /// not implemented
113 gr_slatMeasureEol,
114 /// Amount this slot can stretch (not implemented)
115 gr_slatJStretch,
116 /// Amount this slot can shrink (not implemented)
117 gr_slatJShrink,
118 /// Granularity by which this slot can stretch or shrink (not implemented)
119 gr_slatJStep,
120 /// Justification weight for this glyph (not implemented)
121 gr_slatJWeight,
122 /// Amount this slot mush shrink or stretch in design units
123 gr_slatJWidth = 29,
124 /// SubSegment split point
125 gr_slatSegSplit = gr_slatJStretch + 29,
126 /// User defined attribute, see subattr for user attr number
127 gr_slatUserDefn,
128 /// Bidi level
129 gr_slatBidiLevel = 56,
130 /// Collision flags
131 gr_slatColFlags,
132 /// Collision constraint rectangle left (bl.x)
133 gr_slatColLimitblx,
134 /// Collision constraint rectangle lower (bl.y)
135 gr_slatColLimitbly,
136 /// Collision constraint rectangle right (tr.x)
137 gr_slatColLimittrx,
138 /// Collision constraint rectangle upper (tr.y)
139 gr_slatColLimittry,
140 /// Collision shift x
141 gr_slatColShiftx,
142 /// Collision shift y
143 gr_slatColShifty,
144 /// Collision margin
145 gr_slatColMargin,
146 /// Margin cost weight
147 gr_slatColMarginWt,
148 // Additional glyph that excludes movement near this one:
149 gr_slatColExclGlyph,
150 gr_slatColExclOffx,
151 gr_slatColExclOffy,
152 // Collision sequence enforcing attributes:
153 gr_slatSeqClass,
154 gr_slatSeqProxClass,
155 gr_slatSeqOrder,
156 gr_slatSeqAboveXoff,
157 gr_slatSeqAboveWt,
158 gr_slatSeqBelowXlim,
159 gr_slatSeqBelowWt,
160 gr_slatSeqValignHt,
161 gr_slatSeqValignWt,
162
163 /// not implemented
164 gr_slatMax,
165 /// not implemented
166 gr_slatNoEffect = gr_slatMax + 1
167 };
168
169 enum gr_bidirtl {
170 /// Underlying paragraph direction is RTL
171 gr_rtl = 1,
172 /// Set this to not run the bidi pass internally, even if the font asks for it.
173 /// This presumes that the segment is in a single direction. Most of the time
174 /// this bit should be set unless you know you are passing full paragraphs of text.
175 gr_nobidi = 2,
176 /// Disable auto mirroring for rtl text
177 gr_nomirror = 4
178 };
179
180 typedef struct gr_char_info gr_char_info;
181 typedef struct gr_segment gr_segment;
182 typedef struct gr_slot gr_slot;
183
184 /** Returns Unicode character for a charinfo.
185 *
186 * @param p Pointer to charinfo to return information on.
187 */
188 GR2_API unsigned int gr_cinfo_unicode_char(const gr_char_info* p/*not NULL*/);
189
190 /** Returns breakweight for a charinfo.
191 *
192 * @return Breakweight is a number between -50 and 50 indicating the cost of a
193 * break before or after this character. If the value < 0, the absolute value
194 * is this character's contribution to the overall breakweight before it. If the value
195 * > 0, then the value is this character's contribution to the overall breakweight after it.
196 * The overall breakweight between two characters is the maximum of the breakweight
197 * contributions from the characters either side of it. If a character makes no
198 * contribution to the breakweight on one side of it, the contribution is considered
199 * to be 0.
200 * @param p Pointer to charinfo to return information on.
201 */
202 GR2_API int gr_cinfo_break_weight(const gr_char_info* p/*not NULL*/);
203
204 /** Returns the slot index that after this character is after in the slot stream
205 *
206 * In effect each character is associated with a set of slots and this returns
207 * the index of the last slot in the segment this character is associated with.
208 *
209 * @return after slot index between 0 and gr_seg_n_slots()
210 * @param p Pointer to charinfo to return information on.
211 */
212 GR2_API int gr_cinfo_after(const gr_char_info* p/*not NULL*/);
213
214 /** Returns the slot index that before this character is before in the slot stream
215 *
216 * In effect each character is associated with a set of slots and this returns
217 * the index of the first slot in the segment this character is associated with.
218 *
219 * @return before slot index between 0 and gr_seg_n_slots()
220 * @param p Pointer to charinfo to return information on.
221 */
222 GR2_API int gr_cinfo_before(const gr_char_info* p/*not NULL*/);
223
224 /** Returns the code unit index of this character in the input string
225 *
226 * @return code unit index between 0 and the end of the string
227 * @param p Pointer to charinfo to return information on.
228 */
229 GR2_API size_t gr_cinfo_base(const gr_char_info* p/*not NULL*/);
230
231 /** Returns the number of unicode characters in a string.
232 *
233 * @return number of characters in the string
234 * @param enc Specifies the type of data in the string: utf8, utf16, utf32
235 * @param buffer_begin The start of the string
236 * @param buffer_end Measure up to the first nul or when end is reached, whichever is earliest.
237 * This parameter may be NULL.
238 * @param pError If there is a structural fault in the string, the location is returned
239 * in this variable. If no error occurs, pError will contain NULL. NULL
240 * may be passed for pError if no such information is required.
241 */
242 GR2_API size_t gr_count_unicode_characters(enum gr_encform enc, const void* buffer_begin, const void* buffer_end, const void** pError);
243
244 /** Creates and returns a segment.
245 *
246 * @return a segment that needs seg_destroy called on it. May return NULL if bad problems
247 * in segment processing.
248 * @param font Gives the size of the font in pixels per em for final positioning. If
249 * NULL, positions are returned in design units, i.e. at a ppm of the upem
250 * of the face.
251 * @param face The face containing all the non-size dependent information.
252 * @param script This is a tag containing a script identifier that is used to choose
253 * which graphite table within the font to use. Maybe 0. Tag may be 4 chars
254 * NULL padded in LSBs or space padded in LSBs.
255 * @param pFeats Pointer to a feature values to be used for the segment. Only one
256 * feature values may be used for a segment. If NULL the default features
257 * for the font will be used.
258 * @param enc Specifies what encoding form the string is in (utf8, utf16, utf32)
259 * @param pStart Start of the string
260 * @param nChars Number of unicode characters to process in the string. The string will
261 * be processed either up to the first NULL or until nChars have been
262 * processed. nChars is also used to initialise the internal memory
263 * allocations of the segment. So it is wise not to make nChars too much
264 * greater than the actual number of characters being processed.
265 * @param dir Specifies whether the segment is processed right to left (1) or left to
266 * right (0) and whether to run the internal bidi pass, if a font requests it.
267 * See enum gr_bidirtl for details.
268 */
269 GR2_API gr_segment* gr_make_seg(const gr_font* font, const gr_face* face, gr_uint32 script, const gr_feature_val* pFeats, enum gr_encform enc, const void* pStart, size_t nChars, int dir);
270
271 /** Destroys a segment, freeing the memory.
272 *
273 * @param p The segment to destroy
274 */
275 GR2_API void gr_seg_destroy(gr_segment* p);
276
277 /** Returns the advance for the whole segment.
278 *
279 * Returns the width of the segment up to the next glyph origin after the segment
280 */
281 GR2_API float gr_seg_advance_X(const gr_segment* pSeg/*not NULL*/);
282
283 /** Returns the height advance for the segment. **/
284 GR2_API float gr_seg_advance_Y(const gr_segment* pSeg/*not NULL*/);
285
286 /** Returns the number of gr_char_infos in the segment. **/
287 GR2_API unsigned int gr_seg_n_cinfo(const gr_segment* pSeg/*not NULL*/);
288
289 /** Returns a gr_char_info at a given index in the segment. **/
290 GR2_API const gr_char_info* gr_seg_cinfo(const gr_segment* pSeg/*not NULL*/, unsigned int index/*must be <number_of_CharInfo*/);
291
292 /** Returns the number of glyph gr_slots in the segment. **/
293 GR2_API unsigned int gr_seg_n_slots(const gr_segment* pSeg/*not NULL*/); //one slot per glyph
294
295 /** Returns the first gr_slot in the segment.
296 *
297 * The first slot in a segment has a gr_slot_prev_in_segment() of NULL. Slots are owned
298 * by their segment and are destroyed along with the segment.
299 */
300 GR2_API const gr_slot* gr_seg_first_slot(gr_segment* pSeg/*not NULL*/); //may give a base slot or a slot which is attached to another
301
302 /** Returns the last gr_slot in the segment.
303 *
304 * The last slot in a segment has a gr_slot_next_in_segment() of NULL
305 */
306 GR2_API const gr_slot* gr_seg_last_slot(gr_segment* pSeg/*not NULL*/); //may give a base slot or a slot which is attached to another
307
308 /** Justifies a linked list of slots for a line to a given width
309 *
310 * Passed a pointer to the start of a linked list of slots corresponding to a line, as
311 * set up by gr_slot_linebreak_before, this function will position the glyphs in the line
312 * to take up the given width. It is possible to specify a subrange within the line to process.
313 * This allows skipping of line initial or final whitespace, for example. While this will ensure
314 * that the subrange fits width, the line will still be positioned with the first glyph of the
315 * line at 0. So the resulting positions may be beyond width.
316 *
317 * @return float The resulting width of the range of slots justified.
318 * @param pSeg Pointer to the segment
319 * @param pStart Pointer to the start of the line linked list (including skipped characters)
320 * @param pFont Font to use for positioning
321 * @param width Width in pixels in which to fit the line. If < 0. don't adjust natural width, just run justification passes
322 * to handle line end contextuals, if there are any.
323 * @param flags Indicates line ending types. Default is linked list is a full line
324 * @param pFirst If not NULL, the first slot in the list to be considered part of the line (so can skip)
325 * @param pLast If not NULL, the last slot to process in the line (allow say trailing whitespace to be skipped)
326 */
327 GR2_API float gr_seg_justify(gr_segment* pSeg/*not NULL*/, const gr_slot* pStart/*not NULL*/, const gr_font *pFont, double width, enum gr_justFlags flags, const gr_slot* pFirst, const gr_slot* pLast);
328
329 /** Returns the next slot along in the segment.
330 *
331 * Slots are held in a linked list. This returns the next in the linked list. The slot
332 * may or may not be attached to another slot. Returns NULL at the end of the segment.
333 */
334 GR2_API const gr_slot* gr_slot_next_in_segment(const gr_slot* p);
335
336 /** Returns the previous slot along in the segment.
337 *
338 * Slots are held in a doubly linked list. This returns the previos slot in the linked
339 * list. This slot may or may not be attached to it. Returns NULL at the start of the
340 * segment.
341 */
342 GR2_API const gr_slot* gr_slot_prev_in_segment(const gr_slot* p);
343
344 /** Returns the attachment parent slot of this slot.
345 *
346 * Attached slots form a tree. This returns the parent of this slot in that tree. A
347 * base glyph which is not attached to another glyph, always returns NULL.
348 */
349 GR2_API const gr_slot* gr_slot_attached_to(const gr_slot* p);
350
351 /** Returns the first slot attached to this slot.
352 *
353 * Attached slots form a singly linked list from the parent. This returns the first
354 * slot in that list. Note that this is a reference to another slot that is also in
355 * the main segment doubly linked list.
356 *
357 * if gr_slot_first_attachment(p) != NULL then gr_slot_attached_to(gr_slot_first_attachment(p)) == p.
358 */
359 GR2_API const gr_slot* gr_slot_first_attachment(const gr_slot* p);
360
361 /** Returns the next slot attached to our attachment parent.
362 *
363 * This returns the next slot in the singly linked list of slots attached to this
364 * slot's parent. If there are no more such slots, NULL is returned. If there is
365 * no parent, i.e. the passed slot is a cluster base, then the next cluster base
366 * in graphical order (ltr, even for rtl text) is returned.
367 *
368 * if gr_slot_next_sibling_attachment(p) != NULL then gr_slot_attached_to(gr_slot_next_sibling_attachment(p)) == gr_slot_attached_to(p).
369 */
370 GR2_API const gr_slot* gr_slot_next_sibling_attachment(const gr_slot* p);
371
372
373 /** Returns glyph id of the slot
374 *
375 * Each slot has a glyphid which is rendered at the position given by the slot. This
376 * glyphid is the real glyph to be rendered and never a pseudo glyph.
377 */
378 GR2_API unsigned short gr_slot_gid(const gr_slot* p);
379
380 /** Returns X offset of glyph from start of segment **/
381 GR2_API float gr_slot_origin_X(const gr_slot* p);
382
383 /** Returns Y offset of glyph from start of segment **/
384 GR2_API float gr_slot_origin_Y(const gr_slot* p);
385
386 /** Returns the glyph advance for this glyph as adjusted for kerning
387 *
388 * @param p Slot to give results for
389 * @param face gr_face of the glyphs. May be NULL if unhinted advances used
390 * @param font gr_font to scale for pixel results. If NULL returns design
391 * units advance. If not NULL then returns pixel advance based
392 * on hinted or scaled glyph advances in the font. face must be
393 * passed for hinted advances to be used.
394 */
395 GR2_API float gr_slot_advance_X(const gr_slot* p, const gr_face* face, const gr_font *font);
396
397 /** Returns the vertical advance for the glyph in the slot adjusted for kerning
398 *
399 * Returns design units unless font is not NULL in which case the pixel value
400 * is returned scaled for the given font
401 */
402 GR2_API float gr_slot_advance_Y(const gr_slot* p, const gr_face* face, const gr_font *font);
403
404 /** Returns the gr_char_info index before us
405 *
406 * Returns the index of the gr_char_info that a cursor before this slot, would put
407 * an underlying cursor before. This may also be interpretted as each slot holding
408 * a set of char_infos that it is associated with and this function returning the
409 * index of the char_info with lowest index, from this set.
410 */
411 GR2_API int gr_slot_before(const gr_slot* p/*not NULL*/);
412
413 /** Returns the gr_char_info index after us
414 *
415 * Returns the index of the gr_char_info that a cursor after this slot would put an
416 * underlying cursor after. This may also be interpretted as each slot holding a set
417 * of char_infos that it is associated with and this function returning the index of
418 * the char_info with the highest index, from this set.
419 */
420 GR2_API int gr_slot_after(const gr_slot* p/*not NULL*/);
421
422 /** Returns the index of this slot in the segment
423 *
424 * Returns the index given to this slot during final positioning. This corresponds
425 * to the value returned br gr_cinfo_before() and gr_cinfo_after()
426 */
427 GR2_API unsigned int gr_slot_index(const gr_slot* p/*not NULL*/);
428
429 /** Return a slot attribute value
430 *
431 * Given a slot and an attribute along with a possible subattribute, return the
432 * corresponding value in the slot. See enum gr_attrCode for details of each attribute.
433 */
434 GR2_API int gr_slot_attr(const gr_slot* p/*not NULL*/, const gr_segment* pSeg/*not NULL*/, enum gr_attrCode index, gr_uint8 subindex); //tbd - do we need to expose this?
435
436 /** Returns whether text may be inserted before this glyph.
437 *
438 * This indicates whether a cursor can be put before this slot. It applies to
439 * base glyphs that have no parent as well as attached glyphs that have the
440 * .insert attribute explicitly set to true. This is the primary mechanism
441 * for identifying contiguous sequences of base plus diacritics.
442 */
443 GR2_API int gr_slot_can_insert_before(const gr_slot* p);
444
445 /** Returns the original gr_char_info index this slot refers to.
446 *
447 * Each Slot has a gr_char_info that it originates from. This is that gr_char_info.
448 * The index is passed to gr_seg_cinfo(). This information is useful for testing.
449 */
450 GR2_API int gr_slot_original(const gr_slot* p/*not NULL*/);
451
452 /** Breaks a segment into lines.
453 *
454 * Breaks the slot linked list at the given point in the linked list. It is up
455 * to the application to keep track of the first slot on each line.
456 */
457 GR2_API void gr_slot_linebreak_before(gr_slot *p/*not NULL*/);
458
459 #ifdef __cplusplus
460 }
461 #endif