gdsrip logo


Function List

The following functions are included in gdsriplib.


Initialization

    GdsRip_Initialise

    GdsRip_ReInitLib

 

Information Functions

    GdsRip_GetVersion

    GdsRip_GetParentDir

    GdsRip_QueryGdsDataExtents

    GdsRip_GetTopStructList

    GdsRip_GetNumberOfBands

 

Setup, Execute and Data Collection

    GdsRip_SetupRip

    GdsRip_StartRip

    GdsRip_WaitForBand

    GdsRip_GetRipStatus

    GdsRip_GetProgress

    GdsRip_GetRipImage


Close and Exit

    GdsRip_Close

    GdsRip_ExitRip




Initialization Functions


GdsRip_Initialise

Syntax:

int GdsRip_Initialise(char* ParentDir);

Function:

Initialises the GdsRip library

Inputs:

ParentDir: Path to the directory containing the program that uses the GdsRip library.

Error codes:

failure: non-zero value indicating that an error occurred during initialization.
0(success)

Note:

Must be called at the start of the program before any other function is called.




GdsRip_ReInitLib

Syntax:

int GdsRip_ReInitLib();

Function:

re-initializes the GdsRip library after GdsRip_Close has been called.

Inputs:

-

Error codes:

failure: non-zero value indicating that an error occurred during initialization.
0(success)

Note:

If GdsRip_Close has been called, none of the other GdsRip functions may be used unless the library is re-initialized using GdsRip_ReInitLib.




Information Functions

These functions are called to obtain information about the input data, program version, directories ...



GdsRip_GetVersion

Syntax:

char* GdsRip_GetVersion();

Function:

Returns a string containing GdsRip Library version information. The format of the string is:

<client_name> version <version_number> RCS(<revision_number>) (<month> <day>,<year>)

Inputs:

-

Error codes:

failure: non-zero value indicating that an error occurred during initialization.
0(success)

Example

Gds2Tiff version 1.35 RCS(2.239) (January 09, 2008)



GdsRip_GetParentDir

Syntax:

char* GdsRip_GetParentDir();

Function:

Returns a string that contains the path of the program's parent directory.

Inputs:

-

Error codes:

failure: NULL



GdsRip_QueryGdsDataExtents

Syntax:

(1)
int GdsRip_QueryGdsDataExtents
(const char* GdsFileName, const char* StructureName,
double& x1,double& y1,double& x2,double& y2)

(2)
int GdsRip_QueryGdsDataExtents
(const char* GdsFileName, const char* StructureName,
int layer_cnt,int* layer_list,double& x1,double& y1,
double& x2,double& y2);

(3)
int GdsRip_QueryGdsDataExtents
(const char* GdsFileName, const char* StructureName,
double& x1,double& y1,double& x2,double& y2,
const int imageGridType, const double imageGridValue);

(4)
int GdsRip_QueryGdsDataExtents
(const char* GdsFileName, const char* StructureName,
int layer_cnt,int* layer_list,double& x1,double& y1,
double& x2,double& y2,
const int imageGridType, const double imageGridValue);

Function:

This function is an informational function that can be used to obtain the data extents in GDSII co-ordinates of a given structure for either all layers (prototype 1,3) or for the specified layers (prototype 2,4). Additionally, the user can also specify the DPI (resolution) information of the bit map to be used. This forces the returned coordinates extents to be snapped to the bitmap resolution. Using snapped extents can provide better alignment when multiple layers are rasterized independently.

Input:

GDS File name
Structure name
layer_cnt - number of layers to be considered
layer_list - list of layers to be considered
imageGridType - specifies DPI, DPM or PIXELS
imageGridValue - the actual DPI, DPM or PIXEL value.

Error codes:

0(success)
failure - non zero value

Note:

This function may be called only before GdsRip_SetupRip or after GdsRip_ExitRip/GdsRip_Close; otherwise it will return with an error code.




GdsRip_GetTopStructList

Syntax:

int GdsRip_GetTopStructList(const char* GdsFileName, CGRTopStructList& List);

Function:

This function is a informational function that returns the number of top structures in the specified GDSII file. While most GDSII files have a single top level structure, there are some that have multiple trees and this function, if it returns a list with more than one entity, can then be used to prompt a user for the desired top level structure.

Inputs:

GdsFileName: Name of the GDSII file in question.

Outputs:

List: Data structure containing a list of top structures in the specified GDSII file.

Error codes:

failure: non-zero value.
0(success)

Notes

This function may only be called before GdsRip_SetupRip or after GdsRip_ExitRip/GdsRip_Close;otherwise it will return an error code.

The ‘Size()’ member function of CGRTopStructList returns the number of structures present in the list.




GdsRip_GetNumberOfBands

Syntax:

int GdsRip_GetNumberOfBands()

Function:

Retrives the number of bands to be processed

Input:

-

Error codes:

_GR_ERR_MUTEXH (value < 0)

Note:

If successful, it returns a value > 0 indicating number of bands.




Setup, Execution and Data Collection

These functions are called to set up the RIP, start the RIP, get progress reports on the RIP and collect the results of the RIP.



GdsRip_SetupRip

Syntax:

(UNIX)
int GdsRip_SetupRip(char** ArgumentList);

(WINDOWS)
int GdsRip_SetupRip(char** ArgumentList, HINSTANCE ApplicationContext);

Function:

This function provides setup for the GdsRip Library. Upon callling this function the GdsRip Library reads the specified GDSII file and calculates the size of each rasterized band that is to be returned to the user, as well as the number of such Bands that will be generated based on the user settings specified in the argument list.

Typically this function follows GdsRip_Initialise and precedes GdsRip_StartRip.

Input:

ArgumentList: List of NULL terminated argument strings that specify user settings. See Engine Arguments.

ApplicationContext: Application context of the program using the GdsRip Library.


Error codes:

success: 0

failure: one of the following values

    -1 : The GdsRip Library received a signal to exit. (possibly because of a call to GdsRip_ExitRip)

    _GR_ERR_INVINPUT : The specified input argument list is invalid, possibly null.

    _GR_ERR_LICENSE : The program could not obtain a license for using the GdsRip Library.

    _GR_ERR_MEM : Internal Memory allocation failure occurred while executing this function.

    _GR_ERR_MUTEXH : Internal error while performing this operation.




GdsRip_StartRip

Syntax:

int GdsRip_StartRip(unsigned char* MemChunkPtr);

Function:

This function starts the rasterization of the specified GDSII file based on the user settings.

The size of the memory buffer whose address is passed as 'MemoryChunkPointer' must be greater than or equal to the value of the -ram engine argument (see Engine Arguments) times 1000000.

This function call should be immediately followed by a call to GdsRip_WaitForBand.

This function should be called for the first time after GdsRip_SetupRip or each time GdsRip_WaitForBand returns _RIP_BAND_COMPLETE.

Input:

MemoryChunkPointer: a pointer to the memory buffer that will be used to a "band" of the rasterized image. This memory buffer belongs to the user program.

Error codes:

0 - (success)
_GR_ERR_MUTEXH
_GR_ERR_INVINPUT - returned if memory address pointed by MemChunkPtr is 0 or NULL
_GR_ERR_INVOPR - returned if this function is called while the rip engine is not running.

_GR_ERR_INVINPUT is returned if memory address pointed by MemChunkPtr is 0 or NULL




GdsRip_WaitForBand

Syntax:

int GdsRip_WaitForBand(int MaxWaitTime);

Function:

Puts the calling thread to sleep until either a band has been rasterized or an error has occurred. This function must immediately follow every call to GdsRip_StartRip. If MaxWaitTime is _INDEFINITE, this function will wait forever for the rasterization to complete. If MaxWaitTime is a non-zero positive value, this function will return after the specified time elapses with return code _GR_ERR_TIMEOUT. The user program can take appropriate action by either calling GdsRip_WaitForBand again or calling GdsRip_ExitRip.

Input:

Maximum wait time in milli seconds; default: indefinite wait

Error codes:

0 (success)

_GR_ERR_MUTEXH - internal error

_GR_ERR_TIMEOUT - the wait time elapsed before the band was completed.

_GR_ERR_CLOSE - This operation cannot be executed because the library has exited.(generally because of a call to GdsRip_ExitRip)




GdsRip_GetRipStatus

Syntax:

int GdsRip_GetRipStatus()

Function:

Retrives the current Rip status information

Input:

-

Error codes:

_GR_ERR_MUTEXH ( value < 0 )

Return Values:

_RIP_COMPLETE
_RIP_BAND_COMPLETE
_RIP_EXIT
(rest are for internal use only) (value > 0)

Note:

Operation successfull if return value > 0 and error if return value < 0




GdsRip_GetProgress

Syntax

int GdsRip_GetProgress(CGRProgress& CurrProgress)

Function

Retrives the current Rip progress information

Input

Reference to CGRProgress object to store information

Error codes:

_GR_ERR_MUTEXH, 0(success)




GdsRip_GetRipImage

Syntax:

int GdsRip_GetRipImage(unsigned char** BufferPtr,CGRImageDesc& ImageInfo);

Function:

This function retrieves the rasterized image data after a single Band has been rasterized. This function may only be called only when GdsRip_WaitForBand returns _RIP_BAND_COMPLETE or _RIP_COMPLETE.

If only one buffer is used for rasterization (-nbuff:1 Engine Arguments), the address returned as BufferPtr is same as the one passed to GdsRip_StartRip. If more buffers are used, this address is the one that was passed to the last call to GdsRip_StartRip.

At any given time, the GdsRip library rasterizes only one Band irrespective of the number of memory buffers available for the rasterization process.

Input:

BufferPtr: Pointer to the memory buffer containing the rasterized image data. This memory buffer is typically same as the one passed to GdsRip_StartRip.

ImageInfo: Stores information such as size, band number etc. describing the band that has been rasterized.

Error codes:

0 (success)
_GR_ERR_MUTEXH Internal error.
_GR_ERR_INVINPUT BufferPtr is invalid, possibly null.
_GR_ERR_INVOPR Invalid operation, rasterization is in progress or rasterization has not been initiated.
_GR_ERR_CLOSE : This operation cannot be executed because the library has exited. (because of GdsRip_ExitRip)



Close and Exit

These functions are called to close or exit the library.



GdsRip_Close

Syntax:

int GdsRip_Close();

Function:

This function closes the GdsRip Library and performs cleanup on certain allocated resources.

To re-initialise the library, call GdsRip_ReInitLib.

Do not use this function while the rasterization is in progress. Use GdsRip_ExitRip instead.

Input:

-

Error codes:

0(always)



GdsRip_ExitRip

Syntax:

int GdsRip_ExitRip()

Function:

Informs the Rip Engine to stop ripping and exit, closes the gdsriplib and frees the license.

Input:

-

Error codes:

_GR_ERR_MUTEXH
0(success)

Note:

Must be called at the end of the program