Rather than setting the members of the DT_STREAM_DESC structure one by one, application developers can use the DT_STREAM_FILE, DT_STREAM_MEMORY or DT_STREAM_URL macros to easily create streams that represent files on disk, files in memory (RAM) or files on a local or remote web server. The examples below show how to use these macros.
The following example shows how to use a file stream to initialize D-Type Engine:
DT_STREAM_FILE(sd, "dtype.inf"); if (dtEngineIniViaStream(&engine, &sd, DV_NULL) != 1) exit(0);
The following example shows how to use a file stream to add a font to D-Type Engine's Font Catalog:
DT_ID_SWORD font_format_id = DV_FONT_OPENTYPE_TTF_WINUNICODE; DT_CHAR* fuid = DV_NULL; DT_SWORD fcnr = 0; DT_ID_SWORD cmap_id = -1; DT_ID_UBYTE caching = 128; DT_ID_UBYTE hinting = 1; DT_STREAM_FILE(sd, "/fonts/Hydrogen.ttf"); DT_ID_SWORD font_index = dtFontAddViaStream(engine, font_format_id, fuid, fcnr, cmap_id, caching, hinting, &sd);
Note: The _file_name macro parameter must contain a path that is valid at least until the font represented by font_index is permanently removed from the Font Catalog. Remember that D-Type Font Engine will attempt to access this font at various stages during the execution of your application. If _file_name is invalid or becomes inaccessible while the font is still in use, the corresponding font will become inaccessible to D-Type Font Engine. As a result, your font or some of its glyphs may not render, you may not be able to retrieve various font information etc.
The following example shows how to use a file stream to generate a font:
DT_STREAM_FILE(sd, "output.dtf"); dtFontSaveToStream(engine, font_index, 0, &sd, DV_NULL, DV_NULL);
The following example shows how to use a memory stream to add a font to D-Type Engine's Font Catalog:
DT_ID_SWORD font_format_id = DV_FONT_TYPE1_WINUNICODE; DT_CHAR* fuid = DV_NULL; DT_SWORD fcnr = 0; DT_ID_SWORD cmap_id = -1; DT_ID_UBYTE caching = 128; DT_ID_UBYTE hinting = 1; /* First open a font file from disk */ FILE* f = fopen("fonts/pfb/zombie.pfb", "rb"); if (f == DV_NULL) exit(0); /* Determine the file size */ fseek(f, 0, SEEK_END); DT_SLONG mem_len = ftell(f); rewind(f); /* Allocate memory for this font file */ DT_UBYTE* mem_addr = (DT_UBYTE*)malloc(mem_len); if (mem_addr == DV_NULL) { fclose(f); exit(0); } /* Copy font data to memory and close the file */ fread(mem_addr, 1, mem_len, f); fclose(f); /* Finally, create a memory stream and pass it to D-Type's dtFontAddViaStream function */ DT_STREAM_MEMORY(sd, mem_addr, mem_len); DT_ID_SWORD font_index = dtFontAddViaStream(engine, font_format_id, fuid, fcnr, cmap_id, caching, hinting, &sd);
Note 1: The font file in memory must be in exactly the same format as if it was on disk.
Note 2: The font file must remain at the memory location pointed by the _mem_addr macro parameter at least until the font represented by font_index is permanently removed from the Font Catalog. In other words, this font can be discarded from this memory address only after being permanently removed from the Font Catalog. Remember that D-Type Font Engine will attempt to access this font at various stages during the execution of your application. If _mem_addr becomes invalid while the font is still in use, you will cause access violations in D-Type Font Engine resulting in crashes, memory corruption or other serious problems.
/* Remove the font from the Font Catalog */ dtFontRemove(engine, font_index); /* Now it's OK to release the font from memory */ free(mem_addr);
When a memory based stream is used for writing, D-Type Engine allocates the actual memory buffer for the stream. This memory buffer is always dynamically allocated and must be released by calling the dtFree (or pdFree or txFree) function when the stream is no longer needed. To initialize the DT_STREAM_DESC structure, applications can use the existing DT_STREAM_MEMORY macro. Since D-Type Engine will set the address of the memory buffer and its size, the value of the _mem_addr and _mem_len parameters passed to the DT_STREAM_MEMORY macro is not important. However, we recommend setting _mem_addr to DV_NULL and _mem_len to 0.
The following example shows how to use a memory stream to generate a font:
DT_STREAM_MEMORY(sd, DV_NULL, 0); if (dtFontSaveToStream(engine, font_index, 0, &sd, DV_NULL, DV_NULL) != 1) exit(0); /* At this point we have a font in memory. The sd.stream_locator.mem_w.addr member variable points to a memory buffer that contains the output D-Type font file. This memory buffer was dynamically allocated by D-Type Engine. The sd.stream_locator.mem_w.len member variable indicates the size of the memory file in bytes. */ /* Open a font file on disk */ FILE* f = fopen("output.dtf", "wb"); if (f == DV_NULL) exit(0); /* Copy font data from memory to file */ fwrite(sd.stream_locator.mem_w.addr, 1, sd.stream_locator.mem_w.len, f); /* Close the file */ fclose(f); /* Release memory buffer allocated by D-Type Engine */ dtFree(sd.stream_locator.mem_w.addr);
The following example shows how to use URL, FURL and MURL streams to initialize D-Type Engine:
DT_STREAM_URL(sd, "http://www.remotefontserver.com/config/dtype.inf"); if (dtEngineIniViaStream(&engine, &sd, DV_NULL) != 1) exit(0);
DT_STREAM_FURL(sd, "system/tmp/www_~http://www.remotefontserver.com/config/dtype.inf"); if (dtEngineIniViaStream(&engine, &sd, DV_NULL) != 1) exit(0);
DT_STREAM_MURL(sd, "http://www.remotefontserver.com/config/dtype.inf"); if (dtEngineIniViaStream(&engine, &sd, DV_NULL) != 1) exit(0);
The following example shows how to use a MURL stream to add a font to D-Type Engine's Font Catalog:
DT_ID_SWORD font_format_id = DV_FONT_OPENTYPE_CFF_WINUNICODE; DT_CHAR* fuid = DV_NULL; DT_SWORD fcnr = 0; DT_ID_SWORD cmap_id = -1; DT_ID_UBYTE caching = 128; DT_ID_UBYTE hinting = 1; DT_STREAM_MURL(sd, "http://www.remotefontserver.com:8080/fonts/FreeSansBold.otf"); DT_ID_SWORD font_index = dtFontAddViaStream(engine, font_format_id, fuid, fcnr, cmap_id, caching, hinting, &sd);
Note 1: The above examples are almost identical to the examples showing how to use file streams. The only difference is that the files are now stored on a remote web server and accessed by their URL (Uniform Resource Locator).
Note 2: URL, FURL and MURL stream types are only available on platforms that support Berkeley sockets (e.g. Linux, macOS, Windows).
Note 3: With the URL stream type, the _url macro parameter must contain a URL that is valid at least until the font represented by font_index is permanently removed from the Font Catalog. Remember that D-Type Font Engine will attempt to access this font at various stages during the execution of your application. If _url is invalid or becomes inaccessible (e.g. due to server or connectivity problems) while the font is still in use, the corresponding font will become inaccessible to D-Type Font Engine. As a result, your font or some of its glyphs may not render, you may not be able to retrieve various font information etc.
This combination is not possible. The URL stream type can be used only for reading.