Fungsi ScriptShapeOpenType (usp10.h)

Artikel
08/26/2023

Menghasilkan glyph dan atribut visual untuk eksekusi Unicode dengan informasi OpenType. Setiap eksekusi terdiri dari satu panggilan ke fungsi ini.

Sintaks

HRESULT ScriptShapeOpenType(
  [in, optional] HDC                  hdc,
  [in, out]      SCRIPT_CACHE         *psc,
  [in, out]      SCRIPT_ANALYSIS      *psa,
  [in]           OPENTYPE_TAG         tagScript,
  [in]           OPENTYPE_TAG         tagLangSys,
  [in, optional] int                  *rcRangeChars,
  [in, optional] TEXTRANGE_PROPERTIES **rpRangeProperties,
  [in]           int                  cRanges,
  [in]           const WCHAR          *pwcChars,
  [in]           int                  cChars,
  [in]           int                  cMaxGlyphs,
  [out]          WORD                 *pwLogClust,
  [out]          SCRIPT_CHARPROP      *pCharProps,
  [out]          WORD                 *pwOutGlyphs,
  [out]          SCRIPT_GLYPHPROP     *pOutGlyphProps,
  [out]          int                  *pcGlyphs
);

Parameter

[in, optional] hdc

Menangani konteks perangkat. Untuk informasi selengkapnya, lihat Penembolokan.

[in, out] psc

Arahkan ke struktur SCRIPT_CACHE yang mengidentifikasi cache skrip.

[in, out] psa

Penunjuk ke struktur SCRIPT_ANALYSIS yang diperoleh dari panggilan sebelumnya ke ScriptItemizeOpenType. Struktur mengidentifikasi mesin pembentukan, sehingga glyph dapat dibentuk dengan benar.

Atau, aplikasi dapat mengatur parameter ini ke NULL untuk menerima hasil yang tidak difilter.

[in] tagScript

Struktur OPENTYPE_TAG yang menentukan tag skrip OpenType untuk sistem penulisan.

[in] tagLangSys

Struktur OPENTYPE_TAG yang berisi tag bahasa OpenType untuk sistem penulisan.

[in, optional] rcRangeChars

Array karakter di setiap rentang. Jumlah elemen array ditunjukkan oleh cRanges. Nilai elemen array ini menambah nilai cChars.

[in, optional] rpRangeProperties

Array struktur TEXTRANGE_PROPERTIES , masing-masing mewakili satu rentang fitur OpenType. Jumlah struktur ditunjukkan oleh parameter cRanges . Untuk informasi selengkapnya tentang rpRangeProperties, lihat bagian Keterangan.

[in] cRanges

Jumlah rentang fitur OpenType.

[in] pwcChars

Penunjuk ke array karakter Unicode yang berisi eksekusi.

[in] cChars

Jumlah karakter dalam eksekusi Unicode.

[in] cMaxGlyphs

Jumlah maksimum glyph yang akan dihasilkan.

[out] pwLogClust

Penunjuk ke buffer tempat fungsi ini mengambil array informasi kluster logis. Setiap elemen array sesuai dengan karakter dalam array karakter Unicode. Nilai setiap elemen adalah offset dari glyph pertama dalam eksekusi ke glyph pertama dalam kluster yang berisi karakter yang sesuai. Perhatikan bahwa, ketika anggota fRTL dari struktur SCRIPT_ANALYSISTRUE, elemen berkurang saat array dibaca.

[out] pCharProps

Penunjuk ke buffer tempat fungsi ini mengambil array nilai properti karakter, panjang yang ditunjukkan oleh cChars.

[out] pwOutGlyphs

Penunjuk ke buffer tempat fungsi ini mengambil array glyph.

[out] pOutGlyphProps

Penunjuk ke buffer tempat fungsi ini mengambil array atribut untuk setiap glyph yang diambil. Panjang nilai sama dengan nilai pcGlyphs. Karena satu properti glyph ditunjukkan per glyph, nilai parameter ini menunjukkan jumlah elemen yang ditentukan oleh cMaxGlyphs.

[out] pcGlyphs

Penunjuk ke lokasi di mana fungsi ini mengambil jumlah glyph yang ditunjukkan dalam pwOutGlyphs.

Mengembalikan nilai

Mengembalikan 0 jika berhasil. Fungsi mengembalikan nilai HRESULT bukan nol jika tidak berhasil. Dalam semua kasus kesalahan, konten semua nilai array output tidak terdefinisi.

Pengembalian kesalahan meliputi:

E_OUTOFMEMORY. Panjang buffer output yang ditunjukkan oleh cMaxGlyphs tidak mencukupi.
E_PENDING. Cache skrip yang ditentukan oleh parameter psc tidak berisi informasi yang cukup untuk membentuk string, dan konteks perangkat telah diteruskan sebagai NULL sehingga fungsi tidak dapat menyelesaikan proses pembentukan. Aplikasi harus menyiapkan konteks perangkat yang benar untuk eksekusi dan memanggil fungsi ini lagi dengan nilai konteks yang sesuai dalam hdc dan dengan semua parameter lainnya sama.
USP_E_SCRIPT_NOT_IN_FONT. Font yang sesuai dengan konteks perangkat tidak mendukung skrip yang diperlukan. Aplikasi harus memilih font lain, menggunakan ScriptGetCMap atau metode lain untuk memilih font.

Keterangan

ScriptShapeOpenType lebih disukai daripada fungsi ScriptShape yang lebih lama. Beberapa keuntungan dari ScriptShapeOpenType meliputi yang berikut ini:

Parameter secara langsung sesuai dengan tag OpenType dalam tabel tata letak font.
Parameter menentukan fitur yang diterapkan ke setiap karakter.
Input dibagi menjadi eksekusi. Setiap eksekusi memiliki properti OpenType dan terdiri dari satu panggilan ke ScriptShapeOpenType.

Jika fungsi ini mengembalikan E_OUTOFMEMORY, aplikasi mungkin memanggil ScriptShapeOpenType berulang kali, dengan buffer output yang berturut-turut lebih besar, sampai buffer yang cukup besar disediakan. Jumlah glyph yang dihasilkan oleh titik kode bervariasi sesuai dengan skrip dan font. Untuk skrip sederhana, titik kode Unicode mungkin menghasilkan satu glyph. Namun, font skrip yang kompleks mungkin membuat karakter dari komponen, dan dengan demikian menghasilkan beberapa kali glyph sebagai karakter. Selain itu, ada kasus khusus, seperti representasi karakter yang tidak valid, di mana glyph tambahan ditambahkan untuk mewakili urutan yang tidak valid. Oleh karena itu, tebakan yang wajar untuk ukuran buffer yang ditunjukkan oleh pwOutGlyphs adalah 1,5 kali panjang buffer karakter, ditambah 16 glyph tambahan untuk kasus yang jarang terjadi, misalnya, representasi urutan yang tidak valid.

Fungsi ini dapat mengatur anggota fNoGlyphIndex dari struktur SCRIPT_ANALYSIS jika font atau sistem operasi tidak dapat mendukung indeks glyph.

Aplikasi dapat memanggil ScriptShapeOpenType untuk menentukan apakah font mendukung karakter dalam string tertentu. Jika fungsi mengembalikan S_OK, aplikasi harus memeriksa output untuk glyph yang hilang. Jika fLogicalOrder diatur ke TRUE dalam struktur SCRIPT_ANALYSIS , fungsi selalu menghasilkan glyph dalam urutan yang sama dengan karakter Unicode asli. Jika fLogicalOrder diatur ke FALSE, fungsi menghasilkan item kanan-ke-kiri dalam urutan terbalik sehingga ScriptTextOut tidak harus membalikkannya sebelum memanggil ExtTextOut.

Jika anggota eScriptSCRIPT_ANALYSIS diatur ke SCRIPT_UNDEFINED, pembentukan dinonaktifkan. Dalam hal ini, ScriptShapeOpenType menampilkan glyph yang ada dalam tabel cmap font. Jika tidak ada glyph dalam tabel, fungsi menunjukkan bahwa glyph hilang.

ScriptShapeOpenType mengurutkan kluster secara seragam dalam eksekusi, dan mengurutkan glyph secara seragam dalam kluster. Ini menggunakan nilai anggota fRTLSCRIPT_ANALYSIS, dari ScriptItemizeOpenType, untuk mengidentifikasi apakah pengurutan adalah kiri-ke-kanan atau kanan-ke-kiri.

Untuk parameter rpRangeProperties , struktur TEXTRANGE_PROPERTIES menunjuk ke array struktur OPENTYPE_FEATURE_RECORD . Array ini digunakan sebagai berikut:

Setiap elemen array yang ditunjukkan untuk rpRangeProperties menjelaskan rentang.
Rentang properti tertentu berbagi teks cenderung "bersarang," dan rentang berlapis dapat berbagi informasi OPENTYPE_FEATURE_RECORD . Misalnya, dalam ilustrasi di bawah ini:
- Baris angka di bagian atas mewakili rentang, item, dan eksekusi.
- Setiap rentang berlabel di sini dengan huruf mewakili satu fitur OpenType. Fitur yang termasuk dalam setiap rentang disimpan dalam array OPENTYPE_FEATURE_RECORD dari rentang tersebut.
- Untuk setiap rentang, array struktur OPENTYPE_FEATURE_RECORD sesuai dengan huruf untuk rentang yang berisi rentang tersebut.
- Dalam ilustrasi ini, rentang 2 secara tidak langsung dikaitkan dengan struktur OPENTYPE_FEATURE_RECORD untuk rentang A, B, dan C. Rentang 4 hanya dikaitkan dengan struktur untuk rentang A dan D.

Ilustrasi memperlihatkan rentang, item, eksekusi, dan fitur setiap kata dalam baris teks yang menggunakan enam properti untuk menyajikan delapan kata

Catatan Ilustrasi menggunakan banyak panggilan ke ScriptShapeOpenType, masing-masing mewakili satu eksekusi.

Penting Dimulai dengan Windows 8: Untuk mempertahankan kemampuan untuk berjalan pada Windows 7, modul yang menggunakan Uniscribe harus menentukan Usp10.lib sebelum gdi32.lib dalam daftar pustakanya.

Contoh

Contoh berikut menunjukkan bagaimana ScriptShapeOpenType menghasilkan array kluster logis (pwLogClust) dari array karakter (pwcChars) dan array glyph (pwOutGlyphs). Eksekusi memiliki empat kluster.

Kluster pertama: satu karakter diwakili oleh satu glyph
Kluster kedua: satu karakter diwakili oleh tiga glyph
Kluster ketiga: tiga karakter yang diwakili oleh satu glyph
Kluster keempat: dua karakter yang diwakili oleh tiga glyph

Eksekusi digambarkan sebagai berikut dalam karakter dan array glyph.

Array karakter:

| c1u1 | c2u1 | c3u1 c3u2 c3u3 | c4u1 c4u2 |

Array Glyph:

| c1g1 | c2g1 c2g2 c2g3 | c3g1 | c4g1 c4g2 c4g3 |

Notasi untuk elemen array terdiri dari item ini:

c<n> berarti kluster n.
g<m> berarti glyph m.
u<p> berarti kode Unicode point p.

Array kluster yang dihasilkan menyimpan offset ke kluster yang berisi karakter . Unit dinyatakan dalam glyph.

| 0 | 1 | 4 4 4 | 5 5 |

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	usp10.h
Pustaka	Usp10.lib
DLL	Usp10.dll
Redistribusi	Usp10.dll versi 1.600 atau lebih tinggi di Windows XP