FAQ TBarCode DLL

What Is the Best Way to Create and Draw a Barcode?

In general we suggest this procedure for the API calls:

1. Set all bar code properties; type, text, size mode, module width, orientation, DPI, etc.
2. Call BCCreate() - afterwards do not change any properties.
3. For linear (non multi row) barcodes choose a desired height (by yourself!)
4. Prepare the bounding rectangle: Use a default width and your desired height (step 3). Rotate the rectangle if required (exchange width and height for 90/270°).
5. Retrieve bar code size: BCGetBarcodeSize() - use the prepared (rotated) bounding rectangle (step 4).
6. Now set width and height of drawing rectangle by using the size values returned in step 5. Also consider orientation here.
7. Draw the bar code with this rectangle.

Should I Use a Specific Module Width ?

We suggest to use a custom module width whenever possible - adjusting the narrow bar width gives you more control over the output. It also allows you to comply to specific label requirements and to the printer's output resolution. There may be one exception: For postal bar codes, where the bar code size has to be in an exact range, the bounding rectangle may be sufficient.

Example values for the module width (300 dpi compliant):

• Linear types: 0.254 mm, 0.339 mm
• PDF417: 0.254mm (row height set to 0.762 mm)
• 2D Matrix codes: 0.508 mm

For bitmap output the module width may be adapted to bitmap resolution (e.g. 96 dpi). Here you could use the GetOptimalBitmapSize API call.

I Would Like to Have a Memory Zone, Containing the Whole Pixel Map of the Barcode

Instead of drawing directly to a bitmap or printer DC you can build your own data structure (Pixel map) using TBarCode's Callback functionality. You can pass a custom pointer (your pixel map) to the Callback function and add the current pixel pattern to your structure (in a format as desired).

First set the pointer to your structure or memory block with this function:

BCSetCBData(t_BarCode* pBarCode, LPVOID customData)

This pointer is handled to you in the Callback function:

ERRCODE CALLBACK CustomDrawRow (VOID* customData, t_BarCode* barcode, 
HDC drawDC, HDC targetDC, DOUBLE x, DOUBLE y, DOUBLE width, DOUBLE height);

Now you can store the pattern info (row by row) into your own structure or memory block. After drawing has been finished you have it all in your structure.

How to Encode Binary Data (2D Codes)

Even if you use an escape sequence for binary data the encoder will use code page conversion (example: \x88 leads to a different value in Data Matrix as desired).

Solution:

• Switch off code page conversion (use encoding mode LowByte)
• Force binary encoding mode if available (see PDF417 encoding mode, Data Matrix EnforceBinaryEncoding)

Force C40 Mode in Data Matrix

By default the encoding scheme in Data Matrix is selected automatically for you (based upon input data analysis). If you need C40 mode for any reason, you can pre-select it with the following bar code options string:

BCSetOptions (pBarcode, "DataMatrix_EncodingMode=3");

The mode parameters are as follows: 0 .. optimal, 1 .. enforce binary, 2 .. prefer ASCII, 3 .. prefer C40.

• Please make sure, that the latest version of the TBarCode DLL is used.

Useful Links:

• The API is installed in the Help File ⟶ C:\Program Files\TEC-IT\TBarCode11\Documentation ⟶ TBarCode DLL 11 Developer Reference.chm
• An online API can be found in the TBarCode Library 11.

How to Use Macro 06 in a Data Matrix

Example: You want to encode the following data into a Data Matrix symbol with 26x26 modules (the data below contains already the escape sequences for the GS, RS and EOT):

Problem

That doesn't fit into the 26x26 matrix. The capacity of the 26x26 symbol is 88 numeric or 64 alphanumeric characters. But here we have a mixture of alphanumeric, some special and non-printable characters (GS, RS, EOT) in the data string. By default, we don't use macro mode, which would also save space.

Solution

You can use the Macro 06 mode to save space in the symbol:

BCSet_DM_Format (pBarCode, eDMPr_Macro06)

After enabling the Macro 06, set the barcode data as follows (without header and trailer):

Result: In the data stream, a header of [)> + RS + 06 + GS and a trailer of RS + EOT will be inserted automatically by the bar code reader (no need to set this in the encoded data). This will fit into the 26x26 matrix because with Macro 06 the encoder does not need as much space / internal code words as without.

How to Use Custom Drawing (Callback) in VB

TBarCode V6

'callback function
Public Function MyDrawRow ( ByRef pMyData As Long, 
          ByVal pBarCode As UIntPtr, ByVal hDC As IntPtr, 
          ByVal hTargetDC As IntPtr, 
          ByRef pRect As Rectangle) As UInt32
   Dim strTempo As String
   strTempo = TBC6.BCGetMetaData(pBarCode)
   Return Convert.ToUInt32(0)
End Function

'setting the address of the callback function 
Public cb As TBC6.Callback
   cb = AddressOf MyDrawRow
   eCode = TBC6.BCSetFuncDrawRow(hBarcode, cb, pData)

'required declarations 
Declare Ansi Function BCDrawCB Lib "TBarCode6.ocx" ( _
          ByRef hBarcode As UIntPtr, _
          ByVal hDC As IntPtr, _
          ByRef pRect As Rectangle, _
          ByVal func As Callback, _
          ByVal func As Callback, _
          ByVal pData As IntPtr ) As Int32

Declare Ansi Function BCGetMetaData Lib "TBarCode6.ocx" ( _
           ByVal hBarcode As UIntPtr ) As String

Drawing to Bitmap-DC and Scaling to Screen-DC

DrawBarcode (HDC hDC, long xpos, long ypos)
{
    RECT  hRect;
    long  lHRHeight = 0;

    ypos += GetFullHeight();
    hRect.left     = xpos;
    hRect.top      = ypos;
    hRect.right    = hRect.left   + width;
    hRect.bottom   = hRect.top    + height;

    HDC memDC;
    HBITMAP memBMP, oldBMP;
    int width, height;
    RECT draw;

    width = abs(hRect.right - hRect.left);
    height = abs (hRect.bottom - hRect.top);

    draw.left = 0;
    draw.bottom = height;
    draw.top = 0;
    draw.right = width;

    memDC = CreateCompatibleDC(hDC);
    memBMP = CreateCompatibleBitmap(hDC, width, height);

    oldBMP = (HBITMAP) SelectObject(memDC, memBMP);

    if (S_OK = BCDraw(pBarcode, memDC, &draw))
    {
        // scale / copy to target DC      
        BitBlt(hDC, hRect.left, hRect.top, width, height, memDC, 0, 0, SRCCOPY);
        SelectObject(memDC, oldBMP);
    }      
    DeleteObject(memBMP);
    DeleteDC(memDC);
}

How Can I Get a Bitmap with Optimal Size?

The function BCGetOptimalBitmapSize () returns the optimal size for a bitmap depending on scale factor and adjusted DPI. Please check out the TBarCode Library (DLL) Reference for details.

How Can I Create a Bitmap With a Specific Module Width?

In the code below you just set the module width in[mm] and the total bar code height in[mm]. Via the optimizeToDPI flag you can add also an optimization to the module width (in fact you get the same result as with BCGetOptimalBitmapSize). The sample code is for linear bar codes, but can be adapted to 2D codes as well.

Call this after BCCreate (..)

double moduleWidthUserMM = 0.26;
double heightUserMM = 22.0;
double dpi = 600;
int widthUserPx  = 1; // dummy value, since the width of the bar code is determined by the module width
int heightUserPx = dpi * heightUserMM / 25.4;  // for bitmaps we need [Pixel]
double width, height;
bool optimizeToDPI = TRUE; // adapt module width to next lower full Pixels => avoid quantization errors
int fontSizePt = (int)(0.51 + (10 * moduleWidthUserMM / 0.339)); // auto font size - works well with EAN / Code-128 / Code 39

// bounding rectangle of barcode -> desired drawing coordinates
RECT rect;
rect.left = 0;
rect.right = widthUserPx;
rect.top = 0;
rect.bottom = heightUserPx;

eCode = BCSetDPI(pBarCode, dpi, dpi);
eCode = BCSetIgnoreDpiFromDC(pBarCode, TRUE);

// Ensure that the width of a bar is a multiple of a single pixel (and at minimum one pixel)
eCode = BCSetOptResolution(pBarCode, optimizeToDPI);

// bar code should adapt to module width
eCode = BCSetSizeMode(pBarCode, e_SizeMode::eSizeMode_CustomModuleWidth);

// set module width in [0.001mm]
// we need a rounding delta of 0.001mm in case of optimize flag
eCode = BCSetModWidthN(pBarCode, moduleWidthUserMM * 1000 + (optimizeToDPI?1:0));

eCode = BCSetFontHeight(pBarCode, fontSizePt);

// Calculate bar code size
// for retrieving the size in [Pixel] we need a screen hDC
HDC hDC = GetDC(NULL);
eCode = BCGetBarcodeSize(pBarCode, &rect, hDC, eMUPixel, &width, &height);
if (hDC)
  DeleteDC(hDC);

// Save bitmap with the given module width and size
eCode = BCSaveImage(pBarCode, "C:\\Temp\\Barcode-600dpi.jpg", eIMJpg, int(width + 0.5), (int)(height + 0.5), dpi, dpi);

How Can I Generate a Bitmap Output with Anti-Aliased Font Rendering?

Adjust the Proper DC

Use the following screen DC to create font rendering with anti-aliasing options (as adjusted for the Screen):

HDC dc = CreateDC(TEXT("DISPLAY"),NULL,NULL,NULL);
eCode = BCSaveImageEx(m_pbarCode, dc, file, imageType, 100, widthPx, heightPx, dpi, dpi );

if (dc)
    DeleteDC(dc);

Adjust the Proper Font (LOGFONT)

Use the Windows standard font dialog or the following function to retrieve a pre-initialized LOGFONT structure from Windows GDI:

HFONT hSystemVariableFont = (HFONT ) GetStockObject( ANSI_VAR_FONT );
LOGFONT lfSystemVariableFont;
GetObject ( hSystemVariableFont, sizeof(LOGFONT), &lfSystemVariableFont );

// Make sure that the following flags are set in the LOGFONT structure passed to BCSetLogFont():

lfOutPrecision (e.g. set to 3)
lfClipPrecision (e.g. set to 2)
lfQuality (e.g. set to 1)
lfWeight (e.g. set to 400)

lfFaceName should be set to a True Type font (e.g. “Arial”)

// Calculate the font height as follows:
lfHeight = = -MulDiv( 10 /*PointSize*/, GetDeviceCaps(hDC, LOGPIXELSY), 72);

How to Draw the Barcode with Different DPI in X and Y Axis?

The barcode generator library does not support bitmap export with anisotropic resolution (DPI Y != DPI X). Whenever we have to create our own DC, we create it “isotropic” (DPI Y = DPI X). But there are workarounds as shown below.

Workarounds:

Example - you need DPI X = 1200, DPI Y = 600

A) Anisotropic Device Context

• Use BCDraw (hDC) with a device context, where DPI X = 1200 and DPI Y = 600 is already preset to these values.
• Use Draw(gfx) with a graphics object, where the internal DC is preset to DPI X = 1200 and DPI Y = 600.
• Either don’t call BCSetDPI or use BCSetDPI (pBarcode, -1, -1) ➔ resets the Library DPI to DC default values.
• Don’t set BCIgnoreDPIFromDC because we need the values from the DC or graphics object.
• If you need the bar code image in a bitmap file, you have to create it with your own code from the drawn image in memory.

B) Scale the Image

C/C++ Library

First draw to a bitmap DC with 1200 x 1200 dpi (isotropic) and later scale the image in the Y-axis to 50% = 600 dpi to get your anisotropic result.

• You could use the code from FAQ Drawing to Bitmap-DC and Scaling to Screen-DC as basis.
• When copying the image, use StretchBlt instead of BitBlt to achieve the scaling of the Y-axis (use an ROP and Stretch Mode, which does not create aliasing or softened edges)
  - https://learn.microsoft.com/en-us/windows/win32/api/wingdi/nf-wingdi-stretchblt
  - https://learn.microsoft.com/en-us/windows/win32/gdi/scaling-an-image
• Let TBarCode draw with a high resolution even on a low resolution screen DC:
  If your Bitmap DC is based upon screen resolution (~ 96 dpi), but you want 1200 dpi or something else, you can use the API function BCSetIgnoreDPIFromDC (pBarcode, TRUE) - set it before BCDraw - in combination with BCSetDPI (pBarCode, 1200, 1200). This draws a high resolution bitmap by internally scaling the barcode drawing coordinates. Note that DPI X and DPI Y must be equal here, the target bitmap DC must be large enough to hold the full picture (take care on width/height). The same works also in .NET with similar API functions.

If you need a BMP/JPG/PNG file from your image in memory, you have to use additional bitmap export code (free libraries and sample code publicly available on the web).

.NET API

If you use our .NET API you can do something similar as with StretchBlt (GDI) with the DrawImage() function. First create a “normal” Barcode bitmap and then stretch it or change the DPI – see sample code (or google for more):

• How to resize an image in C#
• Drawing images with DrawImage

C) Custom Drawing

Use our Callback drawing mechanism. You get all the coordinates – either in Millimeters or in a matrix pattern (row pattern). Then you decide on your own, how you scale the X and Y axis coordinates you receive from the library. You receive coordinates in 1/1000 mm resolution from the library and can convert it to Pixel with your own code (and apply your own DPI to X and Y axis). Then draw to a Bitmap DC (GDI Filled Rectangle) or use a Graphics library, which does the work for you (e.g. NET).

Sample code for Custom Drawing (installed with the SDK):

More details:

• TBarCode11 DLL Developer Manual - section “Custom Drawing”
• TBarCode Library Customized Drawing (Callbacks)

Callback drawing is available in the native C/C++ DLL and also in the .NET API (see sample above).

Change Barcode Font Style in Delphi

Create a LOGFONT structure and set it with the BCSetLogFont function.

Function BCSetLogFont
(
  const pBarCode:t_BarCode; // IN : Ptr To Barcode-Definition
  lf:LOGFONT  // IN : TLogFont (TFont) structure
):TErrCode; 
external 'TBarCode8.dll';

Here is a sample of a LOGFONT structure. To adjust the font size, you must change the parameter lfHeight in the structure.

var
  lf:TLogFont;
begin
  lf.lfHeight := 24;          {char height in pixels    }
  lf.lfWidth := 12;           {char width in pixels     }
  lf.lfEscapement := 0;       {orientation of next char }
  lf.lfOrientation := 0;      {orientation of first char}
  lf.lfWeight := FW_NORMAL;   {normal thickness         }
  lf.lfItalic := 0;           {not italic characters    }
  lf.lfUnderline := 0;        {not underlined characters}
  lf.lfStrikeOut := 0;        {not strikeout characters }
  lf.lfCharSet := OEM_CHARSET;{OEM character set        }
  lf.lfOutPrecision := 0;     {default output precision }
  lf.lfClipPrecision := 0;    {default clipping precision}
  lf.lfQuality := DEFAULT_QUALITY; {default scaling quality}
  lf.lfPitchAndFamily := FF_SCRIPT;{default pitch,
                                    script font family   }
  lstrcpy(lf.lfFaceName,'Arial'+chr(0)); {script typeface}

For more information about LOGFONT visit http://msdn.microsoft.com/en-us/library/ms533931(VS.85).aspx

How Can I Use TBarCode Within Java?

We can offer you TBarCode DLL in combination with a Java wrapper using JNI. The currently supported API implements all common functions of TBarCode DLL and can be extended on demand.

The image output functions relevant for web applications are:

public void saveImage(String sFileName, int nType, int nHeight, int nWidth, int nQual)
      throws TBarCodeException

public InputStream saveImage(int nType, int nHeight, int nWidth, int nQual)
      throws TBarCodeException

You can use them for web applications to stream bar code images to the browser.

Encoding Kanji Characters in QR Code® Compaction Mode

Data for QR-Code can be treated either as a sequence of Bytes or as a sequence of SHIFT JIS characters.

Beside SHIFT JIS so-called “ECIs” can be used to switch to different Code-Pages - but ECIs are often unsupported by decoder software.

The default character set of QR-Code is Shift JIS. In order to use the QR-Code Kanji Compaction Mode (more efficient), the input for the encoder must be in a specific character set:

TBarCode DLL V7, TBarCode/X Library Version 7

Input must be in Multi Byte Character Set Format SHIFT JIS (not UTF-8, not Unicode!).

• Single Bytes characters are encoded according to JIS X 0201.
• Double Byte characters are encoded according to Shift JIS X 0208.

TBarCode DLL V8, TBarCode/X Library Version 8 (and later)

Input must be in Unicode (UTF-16 in Windows Version and UTF-32/UCS-4 in Linux/UNIX Version).

Double Byte characters contained in the Shift JIS X 0208-1990 table can be compacted in QR-Code 13-Bit Mode. To enable the compaction in the TBarCode Library you have to call the function

BCSet_QR_KanjiChineseCompaction (pBarcode, eQRMBCompactionKanji)

Here are some links to background information about Kanji and Unicode:

• http://www.rikai.com/library/kanjitables/​kanji_codes.sjis.shtml
• http://en.wikipedia.org/wiki/Shift-JIS
• DBCS/Unicode Mapping Tables: Code Page 932
• http://www.tamasoft.co.jp/en/general-info/sjis.html

How to Encode UTF-8 in a QR-Code

By default TBarCode V9 (and later) will use the following encoding:

• BCSetTextA treats input data as ANSI ASCII (Latin-1). This character set is converted to SHIFT-JIS to be QR-Code compatible. Some Latin-1 characters may be lost in this conversion.
• BCSetTextW treats input data as Unicode. This data is converted to SHIFT-JIS, too (characters not part of SHIFT-JIS may be lost).

• BCSetTextA treats input data as ANSI ASCII (Latin-1). This character set is converted to Latin-1.
• BCSetTextW treats input data as Unicode. This data is converted to Latin-1 (characters not part of Latin-1 may be lost).

If you want to encode data in UTF-8 format, then use BCSetCodePage (pBarCode, eCodePage_UTF8). For non Latin-1 characters use BCSetTextW with Unicode to be sure that all characters can be encoded without loss.

If you want to encode binary data or your own data “as is” (no conversion applies) use: BCSetEncodingMode (pBarCode, eEncMode_LowByte ) with BCSetTextA().

How is the Bar Width Reduction Applied to a 2D Matrix Code?

In Standard Mode, the bar width reduction is applied to each side at 50% of the desired total reduction. If you want to apply the reduction only to the bottom and right side of the matrix dot, use the Legacy Options as shown below.

Standard Mode (Default)

• 4 Pixel / module
• Bar width reduction = 50% → 2 Pixel
• Options: No legacy option set
• We reduce 1 Pixel at each side of a dot or a connected line of dots.

Legacy Mode 1

• 3 Pixel / module
• Bar width reduction = 33% → 1 Pixel
• Options: DRAW_BarWidthReduction_Legacy=1
• We reduce 1 Pixel at right and bottom of each dot, also of connected dots.

Legacy Mode 2

• 4 Pixel / module
• Bar width reduction = 25% → 1 Pixel
• Options: DRAW_BarWidthReduction_Legacy=2
• Connected dots are not reduced.
• We reduce 1 Pixel at right and bottom of each dot or connected line of dots.

How Can I Improve Speed with Save Image?

To speed up the printing of the barcodes, the following options are suggested:

BCBitmapToMemory

Instead of BCSaveImageToBuffer you can use BCBitmapToMemory which should be faster. For more information see API Reference - BCBitmapToMemoryA .

Note that BitmapToMemory does not support font rendering and also uses a different unit when passing the size. If you receive the error code for insufficient memory (eErr_OutOfMemory), increase the buffer size (use the returned *pnSize value) and call the function again. The size of the created bitmap has an influence on the speed as well (but not that much).

Draw Mode

You can change the draw mode to "compatible", which should result in significantly better performance. For more information see API reference - BCSetDrawModeExt .

However, the "compatible" drawing mode sometimes produces enlarged bars/dots (or the opposite), the deviation is 1 pixel. This draw mode uses the GDI Rectangle function – it depends on the graphics/video driver and also on the printer driver if the bars are drawn correctly. In about 90-95% of the use cases the resolution does not matter (the deviation of 1 pixel can be ignored with a 1200 dpi printer), but with low-resolution bitmaps, 1 pixel is already a lot. For this reason, testing is important.

Set this before you call BCDraw or BCSaveImage:

BCSetDrawModeExt (pBarCode, eDrawMode_Compatible);

Multi-Threading

For multithreading you should consider also these hints:

• FAQ TBarCode DLL: How Can I Improve the Speed For Multi-Threading?

How Can I Improve the Speed For Multi-Threading?

There are Critical Sections in BCInitLibrary, DeInitLibrary, BCLicenseMe and BCInitDLL. These are required for initialization of static arrays or copying data. There are also exclusive resources locked (but only briefly) in BCCreate and BCCheck.

Steps to improve speed:

• Call BCInitLibrary and BCLicenseMe only one time at the beginning of the process – not for each bar code creation!
• Per thread: Use the sequence BCAlloc/…/BCCreate/../BCFree for every single bar code creation.
• Per bar code creation (inside of one thread): If you want to create another bar code with different data but the same bar code properties, there is no need for another BCAlloc/../BCFree sequence (that only costs time). Just change the barcode data with BCSetText, recreate the bar code with BCCreate and then draw it.
• BCCheck can be omitted, it is not required with this scenario (since barcode data is also checked in BCCreate).
• The internal memory allocation is more effectively used, if you set barcode data immediately before calling BCCreate(..).