24 </codeblock> <p>If the extended bitmap rasterizer DLL has a cache of previously rasterized extended bitmaps, calls to <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-D24300BA-20D7-34E6-BD23-ED281A0D957E"><apiname>CFbsBitmap::GetScanLine()</apiname></xref>, <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-838CF3C5-C513-33B7-9C81-0EBCE075F6B7"><apiname>CFbsBitmap::GetPixel()</apiname></xref> and <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-57BC8EB1-B9F4-39A9-A18B-594CFB7786B6"><apiname>CFbsBitmap::GetVerticalScanLine()</apiname></xref> do not need to rasterize the bitmap for each call, which can improve performance dramatically. </p> <p>An extended bitmap rasterizer DLL cache contains the previously rasterized content for the most recently used extended bitmaps. Typically the extended bitmap rasterizer DLL adds new bitmaps to the cache when <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-64CF1808-1B05-3403-AB3F-D002F3A4AAFC"><apiname>CFbsRasterizer::BeginBitmap()</apiname></xref> is called (if they are not already in the cache) and does not automatically remove bitmaps from the cache when <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-23EB43C0-1694-39BE-AEFF-1E4ADA30E765"><apiname>CFbsRasterizer::EndBitmap()</apiname></xref> is called. </p> <p>It is possible for an extended bitmap to be deleted before its cached information is deleted from the cache. It is therefore important that the cache does not store pointers to the data that was used to create the pre-rasterized content. </p> <p>There are two approaches that can be used to manage the cache: </p> <ul><li id="GUID-7233E700-FF1D-5FD9-985C-F0FB40643003"><p>Remove the oldest items when a maximum cache size is reached. </p> </li> <li id="GUID-AA32ADA2-6AED-51F2-B7CB-39DA24288F6D"><p>Associate the extended bitmap rasterizer DLL with a <xref href="GUID-6EAFEB3B-D5F1-3CAE-A9F3-5955F891F122.dita"><apiname>CIdle</apiname></xref> active object and remove all of the items during idle times. </p> </li> </ul> <p>It is recommended that you use both mechanisms in order to optimize memory usage. The example extended bitmap rasterizer DLL does this. It maintains a list of recently used bitmaps, with the most recently used one being first in the list. If the size of the cache exceeds the set maximum, the oldest bitmaps are removed until the size is within limits again. The example extended bitmap rasterizer DLL also uses a <xref href="GUID-6EAFEB3B-D5F1-3CAE-A9F3-5955F891F122.dita"><apiname>CIdle</apiname></xref> object that clears the cache during idle times. </p> <p><b>Memory </b> </p> <p>The example extended bitmap rasterizer DLL allocates and frees memory during <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-64CF1808-1B05-3403-AB3F-D002F3A4AAFC"><apiname>CFbsRasterizer::BeginBitmap()</apiname></xref> and <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-23EB43C0-1694-39BE-AEFF-1E4ADA30E765"><apiname>CFbsRasterizer::EndBitmap()</apiname></xref>, respectively. This approach may be slow if frequent allocation and freeing of large amounts of memory is required. </p> <p>A possible solution is to pre-allocate a memory pool from which the extended bitmap rasterizer DLL can use areas of memory. This reduces the number of allocations. However, this solution may be unsuitable for some scenarios, such as when memory usage is more important than performance. </p> </section> <section><title>Example extended bitmap rasterizer</title> <p>The Symbian platform provides a simple example extended bitmap rasterizer, which you can use as a reference when you are creating your own. The source code is located in the <filepath>os\graphics\fbs\fontandbitmapserver\trasterizer\src</filepath> folder. It is built as <filepath>fbsrasterizer_test.dll</filepath> when you build the test code for the Font and Bitmap Server component. </p> <p>This extended bitmap rasterizer DLL handles a tricolor flag. The data comprises the flag's three colors and the direction (horizontal or vertical) of the stripes as shown in the following picture. </p> <fig id="GUID-1EEEB83A-984C-528A-BC5D-5B17836EAA29"><title> |
24 </codeblock> <p>If the extended bitmap rasterizer DLL has a cache of previously rasterized extended bitmaps, calls to <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-D24300BA-20D7-34E6-BD23-ED281A0D957E"><apiname>CFbsBitmap::GetScanLine()</apiname></xref>, <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-838CF3C5-C513-33B7-9C81-0EBCE075F6B7"><apiname>CFbsBitmap::GetPixel()</apiname></xref> and <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita#GUID-683A1D42-2764-3EB7-BD19-9E12559199AB/GUID-57BC8EB1-B9F4-39A9-A18B-594CFB7786B6"><apiname>CFbsBitmap::GetVerticalScanLine()</apiname></xref> do not need to rasterize the bitmap for each call, which can improve performance dramatically. </p> <p>An extended bitmap rasterizer DLL cache contains the previously rasterized content for the most recently used extended bitmaps. Typically the extended bitmap rasterizer DLL adds new bitmaps to the cache when <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-64CF1808-1B05-3403-AB3F-D002F3A4AAFC"><apiname>CFbsRasterizer::BeginBitmap()</apiname></xref> is called (if they are not already in the cache) and does not automatically remove bitmaps from the cache when <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-23EB43C0-1694-39BE-AEFF-1E4ADA30E765"><apiname>CFbsRasterizer::EndBitmap()</apiname></xref> is called. </p> <p>It is possible for an extended bitmap to be deleted before its cached information is deleted from the cache. It is therefore important that the cache does not store pointers to the data that was used to create the pre-rasterized content. </p> <p>There are two approaches that can be used to manage the cache: </p> <ul><li id="GUID-7233E700-FF1D-5FD9-985C-F0FB40643003"><p>Remove the oldest items when a maximum cache size is reached. </p> </li> <li id="GUID-AA32ADA2-6AED-51F2-B7CB-39DA24288F6D"><p>Associate the extended bitmap rasterizer DLL with a <xref href="GUID-6EAFEB3B-D5F1-3CAE-A9F3-5955F891F122.dita"><apiname>CIdle</apiname></xref> active object and remove all of the items during idle times. </p> </li> </ul> <p>It is recommended that you use both mechanisms in order to optimize memory usage. The example extended bitmap rasterizer DLL does this. It maintains a list of recently used bitmaps, with the most recently used one being first in the list. If the size of the cache exceeds the set maximum, the oldest bitmaps are removed until the size is within limits again. The example extended bitmap rasterizer DLL also uses a <xref href="GUID-6EAFEB3B-D5F1-3CAE-A9F3-5955F891F122.dita"><apiname>CIdle</apiname></xref> object that clears the cache during idle times. </p> <p><b>Memory </b> </p> <p>The example extended bitmap rasterizer DLL allocates and frees memory during <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-64CF1808-1B05-3403-AB3F-D002F3A4AAFC"><apiname>CFbsRasterizer::BeginBitmap()</apiname></xref> and <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-23EB43C0-1694-39BE-AEFF-1E4ADA30E765"><apiname>CFbsRasterizer::EndBitmap()</apiname></xref>, respectively. This approach may be slow if frequent allocation and freeing of large amounts of memory is required. </p> <p>A possible solution is to pre-allocate a memory pool from which the extended bitmap rasterizer DLL can use areas of memory. This reduces the number of allocations. However, this solution may be unsuitable for some scenarios, such as when memory usage is more important than performance. </p> </section> <section><title>Example extended bitmap rasterizer</title> <p>The Symbian platform provides a simple example extended bitmap rasterizer, which you can use as a reference when you are creating your own. The source code is located in the <filepath>os\graphics\fbs\fontandbitmapserver\trasterizer\src</filepath> folder. It is built as <filepath>fbsrasterizer_test.dll</filepath> when you build the test code for the Font and Bitmap Server component. </p> <p>This extended bitmap rasterizer DLL handles a tricolor flag. The data comprises the flag's three colors and the direction (horizontal or vertical) of the stripes as shown in the following picture. </p> <fig id="GUID-1EEEB83A-984C-528A-BC5D-5B17836EAA29"><title> |
26 </title> <image href="GUID-538302A3-F4B2-539C-8048-39E6028CB2A2_d0e259004_href.png" placement="inline"/></fig> <ul><li id="GUID-01B79E41-BC48-5BCD-B613-D220BCCF0F48"><p>When <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-64CF1808-1B05-3403-AB3F-D002F3A4AAFC"><apiname>CFbsRasterizer::BeginBitmap()</apiname></xref> is called for this type of extended bitmap, the extended bitmap rasterizer DLL creates a pixel buffer the size of the whole flag and draws the flag into it. If BitGDI specifies a region, the extended bitmap rasterizer DLL draws only the region and otherwise it draws the whole flag. For some extended bitmap rasterizers it may be faster to ignore the region and draw the whole bitmap area. </p> </li> <li id="GUID-9E19CB56-56E4-58FD-A4BD-F3F03305C4AE"><p>Calls to <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-6C2BF4A4-86D1-3489-BA3D-2145E0077705"><apiname>CFbsRasterizer::ScanLine()</apiname></xref> return a pointer to the appropriate place in the pre-rasterized buffer. </p> </li> <li id="GUID-E336F19A-3172-5E7C-82C1-E65968D5F4FB"><p>Calling <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-23EB43C0-1694-39BE-AEFF-1E4ADA30E765"><apiname>CFbsRasterizer::EndBitmap()</apiname></xref> causes the pre-rasterized buffer to be stored in the cache or deleted. </p> </li> </ul> </section> <section><title>Packaging the DLL</title> <p>Because an extended bitmap rasterizer DLL is optional, there is a stub implementation for platform security reasons. When a functional extended bitmap rasterizer DLL is not present, the stub implementation is compiled into a DLL and is installed in the ROM in order to prevent a SIS file installing a rogue DLL with the same name. </p> <p><b>The MMP file </b> </p> <ul><li id="GUID-36A2ABAB-C2B6-519E-85CC-155D56A0E985"><p>The DLL must have the name <filepath>fbsrasterizer.dll</filepath>. If the DLL is renamed during the build process, use the <codeph>LINKAS</codeph> keyword in the MMP file to indicate that this is the final name of the DLL. See <xref href="GUID-946E64D6-3E5D-5264-AD5D-29D3AD296543.dita">Selection of Adaptations</xref> for more information. </p> </li> <li id="GUID-5A5D9A8A-60BD-53F0-B8EB-1CAA1E841C88"><p>Use UIDs 0x1000008D (which indicates a static interface DLL) and 0x10285EAE (which is a unique identifier that indicates that this is an extended bitmap rasterizer DLL). </p> </li> <li id="GUID-0BDEDB09-7118-5822-A27C-4391EB04FA26"><p>The DLL must have all capabilities except TCB (Trusted Computing Base). </p> </li> <li id="GUID-B32F0BA1-5832-57C6-A864-32405357B5C4"><p>Use the <codeph>NOEXPORTLIBRARY</codeph> keyword to prevent the generation of LIB/DSO files during the build process. </p> </li> </ul> <p>Here is a snippet from the stub implementation's MMP file: </p> <codeblock id="GUID-9A970A60-4DE3-58F7-A353-F86777929181" xml:space="preserve">TARGET fbsrasterizer_stub.dll |
26 </title> <image href="GUID-538302A3-F4B2-539C-8048-39E6028CB2A2_d0e265013_href.png" placement="inline"/></fig> <ul><li id="GUID-01B79E41-BC48-5BCD-B613-D220BCCF0F48"><p>When <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-64CF1808-1B05-3403-AB3F-D002F3A4AAFC"><apiname>CFbsRasterizer::BeginBitmap()</apiname></xref> is called for this type of extended bitmap, the extended bitmap rasterizer DLL creates a pixel buffer the size of the whole flag and draws the flag into it. If BitGDI specifies a region, the extended bitmap rasterizer DLL draws only the region and otherwise it draws the whole flag. For some extended bitmap rasterizers it may be faster to ignore the region and draw the whole bitmap area. </p> </li> <li id="GUID-9E19CB56-56E4-58FD-A4BD-F3F03305C4AE"><p>Calls to <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-6C2BF4A4-86D1-3489-BA3D-2145E0077705"><apiname>CFbsRasterizer::ScanLine()</apiname></xref> return a pointer to the appropriate place in the pre-rasterized buffer. </p> </li> <li id="GUID-E336F19A-3172-5E7C-82C1-E65968D5F4FB"><p>Calling <xref href="GUID-FFA11F49-C802-3476-BDF6-41222A800F80.dita#GUID-FFA11F49-C802-3476-BDF6-41222A800F80/GUID-23EB43C0-1694-39BE-AEFF-1E4ADA30E765"><apiname>CFbsRasterizer::EndBitmap()</apiname></xref> causes the pre-rasterized buffer to be stored in the cache or deleted. </p> </li> </ul> </section> <section><title>Packaging the DLL</title> <p>Because an extended bitmap rasterizer DLL is optional, there is a stub implementation for platform security reasons. When a functional extended bitmap rasterizer DLL is not present, the stub implementation is compiled into a DLL and is installed in the ROM in order to prevent a SIS file installing a rogue DLL with the same name. </p> <p><b>The MMP file </b> </p> <ul><li id="GUID-36A2ABAB-C2B6-519E-85CC-155D56A0E985"><p>The DLL must have the name <filepath>fbsrasterizer.dll</filepath>. If the DLL is renamed during the build process, use the <codeph>LINKAS</codeph> keyword in the MMP file to indicate that this is the final name of the DLL. See <xref href="GUID-946E64D6-3E5D-5264-AD5D-29D3AD296543.dita">Selection of Adaptations</xref> for more information. </p> </li> <li id="GUID-5A5D9A8A-60BD-53F0-B8EB-1CAA1E841C88"><p>Use UIDs 0x1000008D (which indicates a static interface DLL) and 0x10285EAE (which is a unique identifier that indicates that this is an extended bitmap rasterizer DLL). </p> </li> <li id="GUID-0BDEDB09-7118-5822-A27C-4391EB04FA26"><p>The DLL must have all capabilities except TCB (Trusted Computing Base). </p> </li> <li id="GUID-B32F0BA1-5832-57C6-A864-32405357B5C4"><p>Use the <codeph>NOEXPORTLIBRARY</codeph> keyword to prevent the generation of LIB/DSO files during the build process. </p> </li> </ul> <p>Here is a snippet from the stub implementation's MMP file: </p> <codeblock id="GUID-9A970A60-4DE3-58F7-A353-F86777929181" xml:space="preserve">TARGET fbsrasterizer_stub.dll |
31 NOEXPORTLIBRARY</codeblock> <p><b>ROM building </b> </p> <p>Building a ROM image for a target platform involves using IBY files. By default the stub implementation is included using the standard mechanism for selecting graphics adaptation components. This is described in <xref href="GUID-946E64D6-3E5D-5264-AD5D-29D3AD296543.dita">Selection of Adaptations</xref>. </p> <p>There is no generic IBY file for the extended bitmap rasterizer. Instead it is included in the main <filepath>fbserv.iby</filepath> file like this: </p> <codeblock id="GUID-9D326323-7148-573E-A792-FD3517047CED" xml:space="preserve">// FBSERV_IBY |
31 NOEXPORTLIBRARY</codeblock> <p><b>ROM building </b> </p> <p>Building a ROM image for a target platform involves using IBY files. By default the stub implementation is included using the standard mechanism for selecting graphics adaptation components. This is described in <xref href="GUID-946E64D6-3E5D-5264-AD5D-29D3AD296543.dita">Selection of Adaptations</xref>. </p> <p>There is no generic IBY file for the extended bitmap rasterizer. Instead it is included in the main <filepath>fbserv.iby</filepath> file like this: </p> <codeblock id="GUID-9D326323-7148-573E-A792-FD3517047CED" xml:space="preserve">// FBSERV_IBY |