diff options
Diffstat (limited to 'common/quicktime_win32/ATSUnicodeDirectAccess.h')
| -rw-r--r-- | common/quicktime_win32/ATSUnicodeDirectAccess.h | 423 |
1 files changed, 423 insertions, 0 deletions
diff --git a/common/quicktime_win32/ATSUnicodeDirectAccess.h b/common/quicktime_win32/ATSUnicodeDirectAccess.h new file mode 100644 index 0000000..0445d58 --- /dev/null +++ b/common/quicktime_win32/ATSUnicodeDirectAccess.h @@ -0,0 +1,423 @@ +/* + File: ATSUnicodeDirectAccess.h + + Contains: Public Interfaces/Types for Low Level ATSUI + + Version: QuickTime 7.3 + + Copyright: (c) 2007 (c) 2002 by Apple Computer, Inc., all rights reserved. + + Bugs?: For bug reports, consult the following page on + the World Wide Web: + + http://developer.apple.com/bugreporter/ + +*/ +#ifndef __ATSUNICODEDIRECTACCESS__ +#define __ATSUNICODEDIRECTACCESS__ + +#ifndef __ATSUNICODE__ +#include <ATSUnicode.h> +#endif + + + + +#if PRAGMA_ONCE +#pragma once +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +#if PRAGMA_IMPORT +#pragma import on +#endif + +/* ---------------------------------------------------------------------------- */ +/* Constants */ +/* ---------------------------------------------------------------------------- */ + +/* + * ATSUDirectDataSelector + * + * Summary: + * These are the data selectors used in the + * ATSUDirectGetLayoutDataArrayPtr function to get the needed layout + * data array pointer. + */ +typedef UInt32 ATSUDirectDataSelector; +enum { + + /* + * Returns the parallel advance delta (delta X) array. (Array Type): + * Fixed (Return Time): Constant, unless creation is necessary, or + * unless requested by ATSUDirectGetLayoutDataArrayPtrFromTextLayout. + * (Creation): This array is created only on demand. Thus, if any + * changes are to be made iCreate should be set to true. If the array + * had not been previously allocated it will be allocated and + * zero-filled when iCreate is set to true. + */ + kATSUDirectDataAdvanceDeltaFixedArray = 0L, + + /* + * Returns the parallel baseline delta (delta Y) array. (Array Type): + * Fixed (Return Time): Constant, unless creation is necessary, or + * unless requested by ATSUDirectGetLayoutDataArrayPtrFromTextLayout. + * (Creation): This array is created only on demand. Thus, if any + * changes are to be made iCreate should be set to true. If the array + * had not been previously allocated it will be allocated and + * zero-filled when iCreate is set to true. + */ + kATSUDirectDataBaselineDeltaFixedArray = 1L, + + /* + * Returns the parallel device delta array for device- specific + * tweaking. This is an array of values which are used to adjust + * truncated fractional values for devices that do not accept + * fractional positioning. It is also used to provide precise + * positioning for connected scripts. (Array Type): SInt16 (Return + * Time): Constant, unless creation is necessary, or unless requested + * by ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This + * array is created only on demand. Thus, if any changes are to be + * made iCreate should be set to true. If the array had not been + * previously allocated it will be allocated and zero-filled when + * iCreate is set to true. + */ + kATSUDirectDataDeviceDeltaSInt16Array = 2L, + + /* + * Returns the parallel style index array. The indexes setting in the + * array are indexes into the the StyleSetting array, which can be + * obtained using the + * kATSUDirectDataStyleSettingATSUStyleSettingRefArray below. (Array + * Type): UInt16 (Return Time): Constant, unless creation is + * necessary, or unless requested by + * ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This + * array is created only on demand. Thus, if any changes are to be + * made iCreate should be set to true. If the array had not been + * previously allocated it will be allocated and zero-filled when + * iCreate is set to true. + */ + kATSUDirectDataStyleIndexUInt16Array = 3L, + + /* + * Returns the style setting ref array. (Array Type): + * ATSUStyleSettingRef (Return Time): Linear, based on the number of + * styles applied to the given line. (Creation): This array is always + * present if the layout has any text assigned to it at all. Setting + * iCreate has no effect. + */ + kATSUDirectDataStyleSettingATSUStyleSettingRefArray = 4L, + + /* + * Returns the ATSLayoutRecord, version 1 array. This should not be + * used directly at all. Rather, use the + * kATSUDirectDataLayoutRecordATSLayoutRecordCurrent selector below. + * This will ensure that the code will always be using the most + * current version of the ATSLayoutRecord, should there ever be a + * change. ATSUI will only ensure the most efficient processing will + * occur for the latest version of ATSLayoutRecord. (Array Type): + * ATSLayoutRecord, version 1 (Return Time): Constant, unless + * creation is necessary, or unless requested by + * ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This + * array is always present if the layout has any text assigned to it + * at all. Setting iCreate has no effect + */ + kATSUDirectDataLayoutRecordATSLayoutRecordVersion1 = 100L, + + /* + * Returns the ATSLayoutRecord. This will return the most current + * version of the ATSLayoutRecord, and the one that's defined in this + * file. Always use kATSUDirectDataLayoutRecordATSLayoutRecordCurrent + * to get the array of ATSLayoutRecords. (Array Type): + * ATSLayoutRecord (Return Time): Constant, unless creation is + * necessary, or unless requested by + * ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This + * array is always present if the layout has any text assigned to it + * at all. Setting iCreate has no effect. + */ + kATSUDirectDataLayoutRecordATSLayoutRecordCurrent = kATSUDirectDataLayoutRecordATSLayoutRecordVersion1 +}; + +/* ---------------------------------------------------------------------------- */ +/* Data Types */ +/* ---------------------------------------------------------------------------- */ + +/* + * ATSUStyleSettingRef + * + * Summary: + * A reference to a style setting object that represents an + * ATSUStyle plus any cached/set information about that style. + */ +typedef struct ATSStyleSetting* ATSUStyleSettingRef; +/* ---------------------------------------------------------------------------- */ +/* Direct Accessors */ +/* ---------------------------------------------------------------------------- */ +/* + * ATSUDirectGetLayoutDataArrayPtrFromLineRef() + * + * Summary: + * Returns the data pointer specified by iDataSelector and + * referenced by iLineRef. + * + * Discussion: + * This function simply returns the data pointer specified by + * iDataSelector and referenced by iLineRef. This data pointer + * should not be freed directly after it's been used. Rather, it + * should be released using ATSUDirectReleaseLayoutDataArrayPtr. + * Doing so serves as a signal to ATSUI that the caller is done with + * the data and that it can merge it in smoothly and adjust its + * internal processes. Furthermore, it may be the case that the + * pointer returned may be dynamically allocated one or contain + * dynamically allocated data. If it's not properly freed, a memory + * leak may result. This function may only be called within the + * context of an ATSUDirectLayoutOperationOverrideUPP callback. The + * pointer returned points to the exact data referenced by the + * ATSUTextLayout object that triggered the callback call. This is + * by far the most efficient way to use the direct access calls + * because for most requested data, no allocation and copy is done. + * Furthermore, because this a direct pointer to the data that ATSUI + * will use for it's layout, the data arrays returned by this can be + * tweaked and edited. Many of the requested arrays are created by + * ATSUI only when necessary. If these arrays are to be altered, + * then be sure to set iCreate to true. This will ensure that this + * array is created. If the arrays are not created, ATSUI + * automatically assumes that all entries in the array are zero. The + * pointer returned by this function is only valid within the + * context of the callback. Do not attempt to retain it for later + * use. + * + * Parameters: + * + * iLineRef: + * The ATSULineRef which was passed into a + * ATSUDirectLayoutOperationOverrideUPP callback function as a + * parameter. + * + * iDataSelector: + * The selector for the data that is being requested. + * + * iCreate: + * If the ATSULineRef passed in iLineRef does not reference the + * requested array, then a zero-filled one will be created and + * returned in oLayoutDataArray if this is set to true. For some + * ATSUDirectDataSelectors, these cannot be simply created. Thus, + * this flag will have no affect on these few + * ATSUDirectDataSelectors. + * + * oLayoutDataArrayPtr: + * Upon sucessful return, this parameter will contain a pointer to + * an array of the requested values if the ATSULineRef passed in + * iLineRef references those values. If this is not the case, then + * NULL will be returned, unless iCreate is set to true and the + * array can be created. This parameter itself may be set to NULL + * if only a count of the entries is needed. + * + * oLayoutDataCount: + * Upon sucessful return, this parameter will contain a count of + * the entries in the array returned in oLayoutDataArray. + * + * Availability: + * Non-Carbon CFM: not available + * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later + * Mac OS X: in version 10.2 and later + */ +EXTERN_API_C( OSStatus ) +ATSUDirectGetLayoutDataArrayPtrFromLineRef( + ATSULineRef iLineRef, + ATSUDirectDataSelector iDataSelector, + Boolean iCreate, + void * oLayoutDataArrayPtr[], /* can be NULL */ + ItemCount * oLayoutDataCount); + + +/* ---------------------------------------------------------------------------- */ +/* + * ATSUDirectGetLayoutDataArrayPtrFromTextLayout() + * + * Summary: + * Returns the data pointer specified by iDataSelector and + * referenced by iTextLayout for the line starting at iLineOffset. + * + * Discussion: + * This function simply returns the data pointer specified by + * iDataSelector and referenced by iTextLayout for the line starting + * at iLineOffset. This data pointer should not be freed directly + * after it's been used. Rather, it should be released using + * ATSUDirectReleaseLayoutDataArrayPtr. Doing so serves as a signal + * to ATSUI that the caller is done with the data. Furthermore, it + * may be the case that the pointer returned may be dynamically + * allocated one or contain dynamically allocated data. If it's not + * properly freed, a memory leak may result. This function may not + * be called inside the context of an + * ATSUDirectLayoutOperationOverrideUPP callback for the + * ATSUTextLayout data that triggered the callback. All data + * returned will be a copy of the data in the object requested. This + * means two things: first of all, this means that it's a very + * inefficient way of using the data. All of the selectors that + * would have returned in constant time now would be forced to + * return in order-n time. Second of all, this means that the + * developer cannot change any of the data. Any changes the + * developer makes to the arrays returned by this API will have no + * effect on the layout. Using the + * kATSULayoutOperationPostLayoutAdjustment operation selector + * override and the ATSUDirectGetLayoutDataArrayPtrFromLineRef is a + * great alternative to using this API. Many of the requested arrays + * are created by ATSUI only when necessary. This means that it's + * possible that this API will return NULL pointer and a count of 0. + * In this case, if there's no error returned, the array simply + * doesn't exist and the caller should treat all of the entries in + * the array that they would have recieved as being 0. + * + * Parameters: + * + * iTextLayout: + * The ATSUTextLayout object from which the requested data will + * come from. + * + * iLineOffset: + * The edge offset that corresponds to the beginning of the range + * of text of the line of the requested data. If the text has + * multiple lines, then ATSUDirectGetLayoutDataArrayPtrFromLineRef + * will need to be called for each of the lines in which the + * requested data is needed. + * + * iDataSelector: + * The selector for the data that is being requested. + * + * oLayoutDataArrayPtr: + * Upon sucessful return, this parameter will contain a pointer to + * an array of the requested values if the ATSUTextLayout passed + * in iTextLayout references those values for the line offset + * iLineOffset. If this is not the case, then NULL will be + * returned. This parameter itself may be set to NULL if only a + * count of the entries is needed. + * + * oLayoutDataCount: + * Upon sucessful return, this parameter will contain a count of + * the entries in the array returned in oLayoutDataArray. + * + * Availability: + * Non-Carbon CFM: not available + * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later + * Mac OS X: in version 10.2 and later + */ +EXTERN_API_C( OSStatus ) +ATSUDirectGetLayoutDataArrayPtrFromTextLayout( + ATSUTextLayout iTextLayout, + UniCharArrayOffset iLineOffset, + ATSUDirectDataSelector iDataSelector, + void * oLayoutDataArrayPtr[], /* can be NULL */ + ItemCount * oLayoutDataCount); + + +/* ---------------------------------------------------------------------------- */ +/* + * ATSUDirectReleaseLayoutDataArrayPtr() + * + * Summary: + * Properly releases of an array pointer returned by + * ATSUDirectGetLayoutDataArrayPtrFromLineRef() or + * ATSUDirectGetLayoutDataArrayPtrFromTextLayout. + * + * Discussion: + * This function is needed to let ATSUI know that the caller is + * finished with the pointer that was previously requested by + * ATSUDirectGetLayoutDataArrayPtrFromLineRef() or + * ATSUDirectGetLayoutDataArrayPtrFromTextLayout(). This is needed + * in case ATSUI needs to make any internal adjustments to it's + * internal structures. + * + * Parameters: + * + * iLineRef: + * The lineRef from which the layout data array pointer came from. + * If the layout data array pointer did not come from a lineRef, + * then set this to NULL. + * + * iDataSelector: + * The selector for which iLayoutDataArrayPtr was obtained. + * + * iLayoutDataArrayPtr: + * A pointer to the layout data array which is to be disposed of. + * + * Availability: + * Non-Carbon CFM: not available + * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later + * Mac OS X: in version 10.2 and later + */ +EXTERN_API_C( OSStatus ) +ATSUDirectReleaseLayoutDataArrayPtr( + ATSULineRef iLineRef, /* can be NULL */ + ATSUDirectDataSelector iDataSelector, + void * iLayoutDataArrayPtr[]); + + +/* ---------------------------------------------------------------------------- */ +/* + * ATSUDirectAddStyleSettingRef() + * + * Summary: + * This function will fetch a style index for the + * ATSUStyleSettingRef passed in. + * + * Discussion: + * This function allows for glyph replacement or substitution from + * one layout or line to another layout or line. Not only will it + * look up the style index for iStyleSettingRef, but if the + * ATSUStyleSettingRef passed in iStyleSettingRef is not yet part of + * the line referenced by iLineRef, it will add it. If there is an + * outstanding ATSUStyleSettingRef array obtained by using the + * kATSUDirectDataStyleSettingATSUStyleSettingRefArray selector, the + * pointer obtained for this may no longer be valid after this + * function has been called. These pointers should be freed before + * calling this function and re-obtained afterwards. + * + * Parameters: + * + * iLineRef: + * An ATSULineRef which was passed into a + * ATSUDirectLayoutOperationOverrideUPP callback function as a + * parameter. + * + * iStyleSettingRef: + * The ATSUStyleSettingRef to be looked up or added to the + * ATSUTextLayout referenced by iTextLayout for the line starting + * at the offset iLineOffset. + * + * oStyleIndex: + * Upon sucessful return, this will parameter will be set to the + * index of the ATSUStyleSettingRef passed in iStyleSettingRef for + * the line referenced by iLineRef. If the ATSUStyleSettingRef + * does not exist, in that context, then it will be added and the + * new index will be returned here. + * + * Availability: + * Non-Carbon CFM: not available + * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later + * Mac OS X: in version 10.2 and later + */ +EXTERN_API_C( OSStatus ) +ATSUDirectAddStyleSettingRef( + ATSULineRef iLineRef, + ATSUStyleSettingRef iStyleSettingRef, + UInt16 * oStyleIndex); + + + + +#ifdef PRAGMA_IMPORT_OFF +#pragma import off +#elif PRAGMA_IMPORT +#pragma import reset +#endif + +#ifdef __cplusplus +} +#endif + +#endif /* __ATSUNICODEDIRECTACCESS__ */ + |