GerbLib Functions

GerbLib exports the following functions.

GbxConvert

The GbxConvert function converts a RS274x Gerber file to PDF, Postscript, TIFF, BMP or RID files. The output file format is specified by the output filename extension. 

UINT GbxConvert(
    CHAR *Inname,
    CHAR *Outname,
    BOOL bBlock
);

Parameters

Inname

[in] Pointer to a null-terminated string that specifies the filename of an existing Gerber file.

Outname

[in] Pointer to a null-terminated string that specifies the name of the output file. The string must have a proper extension which is one of .pdf, .ps, .eps, .tif, .bmp, and .rid.

bBlock

[in] Boolean to specify whether the function should block.

Return Values

        GBX_PENDING    There is a previous conversion in progress. The function returned without doing anything. 
        GBX_READING    The Gerber file is still being read. The current conversion operation is still in progress.
        GBX_WRITING    The output file is still being written to. The current conversion operation is still in progress.
        GBX_SUCCESS    The conversion has been completed successfully.
        GBX_FILE_NOT_FOUND    The input file cannot be opened. The conversion failed.
        GBX_BAD_FILE_EXT    The output file name extension is unrecognized. The conversion failed.
        GBX_NO_GBX        GerbMagic not found. You must install GerbMagic before using GbxConvert.
        GBX_BAD_VERSION    The installed GerbMagic is too old. Must have GerbMagic 3.2 or later installed.
        GBX_FAIL    The operation failed. Possibly not enough disk space or no proper license found.

Remarks

When called in a single process, GbxConvert can only do a single conversion at one time. The user should wait until the previous operation is completed before making a second call. If a conversion is still in progress while GbxConvert is being called, GbxConvert simply returns GBX_PENDING without doing anything. To convert mutilple Gerber files simultaneously, call GbxConvert from multiple processes.

If bBlock is TRUE, the function does not return until the conversion operation has been completed or an error is detected. If bBlock is FALSE the function returns immedately. If the return value is either GBX_READING or GBX_WRITING, this indicates the operation is still in progress in the background. The user can subsequently call GbxCheckState to check and wait for the operation to finish.

Wildcards are not supported in the filenames. If Inname cannot be found, the function fails with a return value of GBX_FILE_NOT_FOUND. Outname must contain a proper file extension, which must be one of:

         .pdf, .ps, .eps, .tif, .bmp, .rid

If an extension other than the above is supplied, the function immediately returns GBX_BAD_FILE_EXT.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxCheckState

The GbxCheckState function checks the state of the conversion operation in progress. This function is called by the user after GbxConvert returns either GBX_READING or GBX_WRITING, which means the operation is still in progress in the background.

UINT GbxCheckState(
    DWORD *dwPercent,
    DWORD dwMilliseconds
);

Parameters

dwPercent

[out] Pointer supplied by the caller to receive a value regarding the percentage of the operation finished. For instance, if dwPercent returns 85, it means 85% of the operation has finished. dwPercent is never larger than 100.

dwMiliseconds

[in] Specifies the time-out interval, in milliseconds. The function returns when the interval elapses, even if the operation has not finished. If dwMilliseconds is zero, the function immediately returns the operation status. 

Return Values

The return value of GbxCheckState is the current state of the operation. It can be one of the following:
        GBX_READING    The Gerber file is still being read. The operation is still in progress.
        GBX_WRITING    The output file is still being written to. The operation is still in progress.
        GBX_SUCCESS    The conversion has been completed successfully.
        GBX_FAIL    The operation failed. Possibly not enough disk space or no proper license found.

Remarks

GbxCheckState checks the current state of the conversion. If the operation has not finished, the calling thread enters the wait state. It uses no processor time while waiting for the operation to finish or the time-out interval to elapse. 

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxAbort

The GbxAbort function aborts the reading or writing operation in progress. If there is no operation in progress, this function does nothing.

VOID GbxAbort(VOID);

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxGetResolution

The GbxGetResolution function gets the currently used resolution value.

UINT GbxGetResolution(
    DWORD *dwDPI
);

Parameters

dwDPI

[out] Pointer supplied by the caller to receive the resolution value in Dot Per Inch (DPI).

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Remarks

The resolution is only used when converting Gerber files to raster image formats like BMP, TIF, and RID. It's not used when converting to vector image formats like PDF and PostScript.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxSetResolution

The GbxSetResolution function sets the currently used resolution value.

UINT GbxSetResolution(
    DWORD dwDPI
);

Parameters

dwDPI

[in] Tthe resolution value in Dot Per Inch (DPI).

Return Values

GBX_SUCCESS           Succeeded
GBX_READING           Failed because a file is being read.
GBX_WRITING            Failed because a file is being written to.
GBX_FAIL                    Failed for some other reason.

Remarks

The user should call this function when there is no conversion operation in progress. Otherwise the return value is either GBX_READING or GBX_WRITING, indicating the status of the current conversion operation. 

The resolution is only used when converting Gerber files to raster image formats like BMP, TIF, and RID. It's not used when converting to vector image formats like PDF and PostScript.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxGetPageSize

The GbxGetPageSize function gets the currently used page size. 

UINT 
GbxGetPageSize(
    double *width, 
    double *height
);

Parameters

width

[out] Pointer supplied by the caller to receive the width of the page in Inches.

height

[out] Pointer supplied by the caller to receive the height of the page in Inches.

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Remarks

The "page size" is the size of the canvas on which the image is drawn. The "page size" is usually larger than the image itself. The "page size" setting is only effective when the bOutputWholePage parameter is set to TRUE. See GbxSetOutputMode for more information.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxSetPageSize

The GbxSetPageSize function sets the current page size. 

UINT 
GbxSetPageSize(
    double width, 
    double height
);

Parameters

width

[in]  The width of the page in Inches.

height

[in] The height of the page in Inches.

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Return Values

GBX_SUCCESS           Succeeded
GBX_READING           Failed because a file is being read.
GBX_WRITING            Failed because a file is being written to.
GBX_FAIL                    Failed for some other reason.

Remarks

The user should call this function when there is no conversion operation in progress. Otherwise the return value is either GBX_READING or GBX_WRITING, indicating the status of the current conversion operation. 

The "page size" is the size of the canvas on which the image is drawn. The "page size" is usually larger than the image itself. The "page size" setting is only effective when the bOutputWholePage parameter is set as TRUE. See GbxSetOutputMode for more information.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxSetLeftRightMargin

The GbxSetLeftRightMargin function sets the left and right margin of the image. 

UINT GbxSetLeftRightMargin(
    double margin
);

Parameters

margin

[in]  The left and right margin of the image in Inches.

Return Values

GBX_SUCCESS           Succeeded
GBX_READING           Failed because a file is being read.
GBX_WRITING            Failed because a file is being written to.
GBX_FAIL                    Failed for some other reason.

Remarks

The user should call this function when there is no conversion operation in progress. Otherwise the return value is either GBX_READING or GBX_WRITING, indicating the status of the current conversion operation. 

The margin is used when the image is automatically aligned to a border. For example, when the image is auto-aligned to the left border, the left margin is the distance between the left-most coordinate and the left border of the canvas. The same rule applies then auto-aligned to the right border. See the AutoAlign parameter of GbxSetOutputMode function for more information.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxGetLeftRightMargin

The GbxGetLeftRightMargin function gets the left and right margin of the image. 

UINT GbxGetLeftRightMargin(
    double *margin
);

Parameters

margin

[out]  Pointer supplied by the caller to receive the left and right margin of the image in Inches.

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Remarks

The margin is used when the image is automatically aligned to a border. For example, when the image is auto-aligned to the left border, the left margin is the distance between the left-most coordinate and the left border of the canvas. The same rule applies then auto-aligned to the right border. See the AutoAlign parameter of GbxSetOutputMode function for more information.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxSetTopBottomMargin

The GbxSetTopBottomMargin function gets the top and bottom margin of the image. 

UINT GbxSetTopBottomMargin(
    double margin
);

Parameters

margin

[in]  The top and bottom margin of the image in Inches.

Return Values

GBX_SUCCESS           Succeeded
GBX_READING           Failed because a file is being read.
GBX_WRITING            Failed because a file is being written to.
GBX_FAIL                    Failed for some other reason.

Remarks

The user should call this function when there is no conversion operation in progress. Otherwise the return value is either GBX_READING or GBX_WRITING, indicating the status of the current conversion operation. 

The margin is used when the image is automatically aligned to a border. For example, when the image is auto-aligned to the top border, the top margin is the distance between the top-most coordinate and the top border of the canvas. The same rule applies then auto-aligned to the bottom border. See the AutoAlign parameter of GbxSetOutputMode function for more information.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxGetTopBottomMargin

The GbxGetTopBottomMargin function gets the top and bottom margin of the image. 

UINT GbxGetTopBottomMargin(
    double *margin
);

Parameters

margin

[out]  Pointer supplied by the caller to receive the top and bottom margin of the image in Inches.

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Remarks

The margin is used when the image is automatically aligned to a border. For example, when the image is auto-aligned to the top border, the top margin is the distance between the top-most coordinate and the top border of the canvas. The same rule applies then auto-aligned to the bottom border. See the AutoAlign parameter of GbxSetOutputMode function for more information.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxSetOutputMode

The GbxSetOutputMode function sets the output mode.

UINT GbxSetOutputMode(
    BOOL bOutputWholePage, 
    DWORD AutoAlign
);

Parameters

bOutputWholePage

[in]  If TRUE, indicates that when generating one of the output file formats( PDF, PS, TIF, BMP, RID), the image will be drawn on an canvas who's size is set by the GbxSetPageSize function. If FALSE, indicates that when generating one of the output file formats, the canvas size will be reduced to exclude as much blank area as possible. The final output file will contain the image itself plus the margins set by GbxSetLeftRightMargin and GbxSetTopBottomMargin functions.

 

AutoAlign

[in] Automatically align the image to one of the borders. This parameter can be one of the following values:
AL_NONE                    Do not align the image to any border

AL_TOP                        Align the image to the top border

AL_BOT                        Align the image to the bottom border

AL_LEFT                       Align the image to the left border

AL_RIGHT                    Align the image to the right border
AL_BOTLEFT               Align the image to the bottom and left borders

AL_TOPLEFT                Align the image to the top and left borders

AL_TOPRIGHT             Align the image to the top and right borders

AL_BOTRIGHT             Align the image to the bottom and right borders

Return Values

GBX_SUCCESS           Succeeded
GBX_READING           Failed because a file is being read.
GBX_WRITING            Failed because a file is being written to.
GBX_FAIL                    Failed for some other reason.

Remarks

The user should call this function when there is no conversion operation in progress. Otherwise the return value is either GBX_READING or GBX_WRITING, indicating the status of the current conversion operation. 

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxGetOutputMode

The GbxGetOutputMode function gets the output mode.

UINT GbxGetOutputMode(
    BOOL *bOutputWholePage, 
    DWORD *AutoAlign
);

Parameters

bOutputWholePage

[out]  Pointer supplied the the caller to receive the output mode value. See GbxSetOutputMode function for the meaning of this parameter.

 

AutoAlign

[out] Pointer supplied the the caller to receive one of the following values:
AL_NONE                    Do not align the image to any border

AL_TOP                        Align the image to the top border

AL_BOT                        Align the image to the bottom border

AL_LEFT                       Align the image to the left border

AL_RIGHT                    Align the image to the right border
AL_BOTLEFT               Align the image to the bottom and left borders

AL_TOPLEFT                Align the image to the top and left borders

AL_TOPRIGHT             Align the image to the top and right borders

AL_BOTRIGHT             Align the image to the bottom and right borders

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib

GbxGetImgSize

The GbxGetImgSize function returns the size of the image described by a Gerber file.

UINT GbxGetImgSize(
    char *fname, 
    double *sizex, 
    double *sizey
);

Parameters

fname

[in]  A null terminated string supplied by the caller to specify the name of the Gerber file who's size is to be returned.

sizex

[out] Pointer supplied by the caller to receive the width of the image. This value is the largest x-coordinate minus the smallest x-coordinate in the Gerber file.

sizey

[out] Pointer supplied by the caller to receive the height of the image. This value is the largest y-coordinate minus the smallest y-coordinate in the Gerber file.

Return Values

The function returns GBX_SUCCESS on success and GBX_FAIL on failure.

Remarks

This function reads the Gerber file into memory and finds it's largest and smallest coordinates to determine the size of the image. Depending on the file size, this function may take a long time before it returns. The user can call this function to determine the size of an image so he/she can subsequently adjust the page size by calling GbxSetPageSize.

Requirements

  Windows NT/2000/XP/95/98/Me.
  GerbMagic Version 3.2 or later.
  Header: include GerbLib.h.
  Library: Use GerbLib.lib