List of Functions for ODB_RIP

The following functions are used to first open an ODB++ file, report its contents (in terms of steps/layers) and then enable a user to rasterize a step/layer combination. There are additional functions for reporting progress.

ODB	Raster	Other
ODB_RipOpen	ODB_RipSetup	ODB_RipInit
ODB_RipFreeInfo	ODB_RipStart	ODB_RipGetVer
ODB_RipSettings	ODB_RipWaitForBand	ODB_RipExit
	ODB_RipGetRipStatus	ODB_RipCancel
	ODB_RipGetProgress
	ODB_RipGetRipImage
	ODB_RipGetNumberOfBands

ODB_RipInit

Description

Initializes the ODBRIP library (call ONCE at the very beginning).

Syntax

int ODB_RipInit(const char* exec, void *app = NULL, int memstats = 0);

exec      - full executable path

Return:   0 if successful and < 0 if failed

Description

Reads the ODB internal database and initializes the ODBRIP library.

The function can open either a compressed tar file (.tgz) or a directory which should be the top level of an ODB++ hierarchy. The difference is detected automatically. As part of opening the file this function also builds a list of steps, their extents (using the profile), layers and children.

Syntax

int ODB_RipOpen(const sOPENSETTING& opn, sODBTREE& info, bool regen = true);

open      - ODB++ open setting
            open.mInput      - ODB++ input filename
            open.mWorkDir:   - Working directory
            open.mArgs:      - Additional arguments. The possible additional args are:
            -log                        :enable log file
            -dbg                        :enable debugging (if -log)
            -keep_tmpfiles              :to keep intermmediate files
            -nocopyin                   :do not make a copy of the input ODB++ directory
            -reuse                      :reuse ODB intermediate files
            -thrnum:[int_val]           :to set the max thread
info       - reference to the odbtree (alloc/dealloc managed by IOdbRip);

regen:     - Regeneration of ODB intermediate files (must be set to true or the result of ODB_RipRegen)
             if regen is false, ODBTREE info will be empty

			 
Return: 0 if successful and < 0 if failed 

ODB_RipFreeInfo

Description

This function frees the memory after you are done with the data (step and layer info) produced by ODB_RipOpen.

Syntax

ODB_RipFreeInfo ();

Description

This function defines settings and controls that affect how the library converts the native ODB++ data into polygonal data presented to the rasterizer. The g2k arguments are those related to emulation mode for certain plotter manufacturers.

Syntax

int ODB_RipSettings (int argc, char ** argv)

Arguments

argc - the number of arguments in the list argv

argv - a list of arguments shown below:

-arcres:<res_dbl_val> :arcres

-arcsag:<sag_dbl_val> :arcsag

-scale:<scale_dbl_val> :scale

-g2k_ver:<0 | 1 | 2 | 3> :emulation version

-g2k_order:<0 | 1> :translation order

-g2k_break_sr:<0 | 1 | 2> :break SR on or off

-g2k_scale_mode:<1 | 2 | 3> :scaling mode

-g2k_anchor:<0 | 1 | 2 | 3> :anchor mode

-g2k_inch_anchor:<x,y> :anchor inch value

-g2k_mm_anchor:<x,y> :anchor mm value

-g2k_offset:<0 | 1 | 2 | 3 | 4 | 5> :offset mode

-g2k_inch_offset:<x,y> :offset inch value

-g2k_mm_offset:<x,y> :offset mm value

-out_scale:<default | sf |scale | local> :to set the out_scale mode (g2k_ver is 0)

Raster Related Function Calls

The functions listed below are for setting up and calling the raster portion of the library. By the time you get to using these functions you have already opened the ODB++ data and selected a step/layer to process.

Note that the library does not allocate buffer memory required to hold the bitmap. It is the calling application's responsibility to allocate and manage this memory.

Description

This function provides setup for the ODB_RIP Library. Upon calling this function the library converts ODB++ 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.
This function follows ODB_RipSettings.

Syntax

int ODB_RipSetup(const sODBSETTING& odb, const sRIPSETTING& rip, bool regen = true);

Arguments

odb:      - ODB++ convert settings
          odb.mOutDir                           - ODB++ output directory
          odb.mStep                             - ODB++ step to process
          odb.mLayer                            - ODB++ layer to process
          odb.mArgs:                            - ODB++ additional arguments. The possible additional args are:
            -out_scale:[default|sf|scale|local] :to set the out_scale mode (g2k_ver is 0)
            -show_progress                      :to show convert/rip progress
            -unit:[mm/inch]                     :set output unit (default is mm)
            -arcres:[val]                       :set arcres
            -arcsag:[val]                       :set arcsag/chord error
             
            -g2k_ver:[0|1|2|3]                  :emulation version
            -g2k_order:[0|1]                    :translation order
            -g2k_break_sr:[0|1|2]               :break SR on or off
            -g2k_scale_mode:[1|2|3]             :scaling mode
            -g2k_anchor:[0|1|2|3]               :anchor mode
            -g2k_inch_anchor:[x,y]              :anchor inch value
            -g2k_mm_anchor:[x,y]                :anchor mm value
            -g2k_offset:[0|1|2|3|4|5]           :offset mode
            -g2k_inch_offset:[x,y]              :offset inch value 
            -g2k_mm_offset:[x,y]                :offset mm value 

rip:      - RIP settings
          rip.mRam                              - Rip size of raster buffer used to hold the bitmap in memory (in MBytes)
          rip.mDPI:                             - Rip dots per inch resolution
          rip.mFMul:                            - Arc resolution fineness multiplier
          rip.mArgs:                            - Rip additional arguments. The possible additional args are:
            -extents:[LLx,LLy,URx,URy]          :extents of the incoming data to plot instead of the step's profile extents.
            -margin:[x]                         :adds a margin of x units
            -complement                         :reverses the polarity of the bitmap
            -degrees:[90|180|270|-90|-180|-270]
            -scale:[scalex,scaley]
            -mirrorx
            -mirrory

regen:    - Regeneration of ODB intermediate files (must be set to true or the result of ODB_RipRegen)

Error Codes

0 = success

< 0 = Fail

Description

This function is used to start the rasterization of the ODB++ data.

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 ODBRIP_MBMULT.
This must be called after ODB_RipSetup and after ODB_RipWaitForBand returns ODBRIP_BAND_COMPLETE.
This must be immediately followed by a call to ODB_RipWaitForBand.

Syntax

int ODB_RipStart(unsigned char* buffer, const int bufsize);

Arguments

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

< 0 = Fail

Description

This function is used to "wait" while the ODB_RIP processes a band of data. ODB_RipWaitForBand must immediately follow every call to ODB_RipStart.

MaxWaitTime should be a non-zero positive value; after this amount of time elapses, the function will return with code _GR_ERR_TIMEOUT. if ODBRIP_INDEFINITE, this function will wait forever for the rasterization to complete.

The calling application can then take appropriate action (such as a call to progress) and then by either calling ODB_RipWaitForBand again or calling ODB_RipExit.

Syntax

int ODB_RipWaitForBand(const int waittime = ODBRIP_INDEFINITE);

Arguments

MaxWaitTime - time in milliseconds that the function should wait before returning.

Return Codes

Success is indicated by one of the following:

_RIP_BAND_COMPLETE : The library has rasterized one Band. The memory buffer passed to ODB_RipStartRip contains the rasterized image data.

_RIP_COMPLETE : The last Band has been rasterized. There are no more Bands to be rasterized.




Failure: one of the following values

_GR_ERR_MUTEXH : Internal error.

_GR_ERR_TIMEOUT: The specified wait time elapsed but the rasterization process is not complete.

_GR_ERR_CLOSE : This operation cannot be executed because the library has exited. (because of ODBRip_Exit)

Description

Retrieves the current RIP status.

Syntax

int ODB_RipGetRipStatus()

Return Codes

_RIP_COMPLETE

_RIP_BAND_COMPLETE

_RIP_EXIT

(rest are for internal use only) (value > 0)

Description

Retrieves the current rip progress information. Can be used to provide an end user with progress updates.

Syntax

int ODB_RipGetProgress();

Arguments

Reference to CGRProgress object to store information

Returns

Success 0

Error _GR_ERROR_MUTEXH

Description

This function retrieves the rasterized image using the buffer passed in ODB_RipStart after a single Band has been rasterized.
This may only be called after ODB_RipWaitForBand returns ODBRIP_BAND_COMPLETE or ODBRIP_COMPLETE.

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

Syntax

int ODB_RipGetRipImage(sIMAGEDESC& info); 

Arguments

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

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

Returns

0 - success

< 0 - fail

Description

This function tells the calling program how many bands will be generated to cover the complete image area.

Syntax

int ODB_RipGetNumberOfBands() 

Returns

A value > 0 indicates the number of bands

_GR_ERR_MUTEXH (value < 0)

Description

Cancels the ongoing rip, must call ODB_RipSetup before restarting rip.

Syntax

void ODB_RipCancel(char *msg = NULL);

Returns

0 (always)

Description

This function is used close out the raster portion of the library; it can stop the rasterization if it is in progress. Normally one calls this as soon as the raster portion of the library is no longer needed or if an error has occured and the raster module must be shut down.

Syntax

int ODB_RipExit();

Returns

0 (always)

Description

Used to identify the version of the ODB_Rip library.

Syntax

char* ODB_RipGetVersion();

Returns

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>)

Description

ODB_RipRegen checks if we can reuse previous run.

Syntax

bool ODB_RipRegen(const sOPENSETTING& opn, const sODBSETTING& odb, const sRIPSETTING& rip);
bool ODB_RipRegen(const sOPENSETTING& opn, const sGREYSETTING& grey);

Description

ODB_RipCleanup provides cleanup for the Library. This must be called after all the bands has been rasterized, after cancel, after errors of after ODB_RipGreyLevel.
unloadlib: set to true if called after running the last window.

Syntax

void ODB_RipCleanup(bool unloadlib = true);

Returns

0 - success

< 0 - fail

Description

ODB_RipClose closes the ODB internal database and removes intermediate files

Syntax

int ODB_RipClose();

Description

ODB_RipSetup - provides setup for the ODB_RIP Library. Upon calling this function the library converts ODB++ 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.
This function follows ODB_RipSettings.

odb:      - ODB++ convert settings
          odb.mOutDir                           - ODB++ output directory
          odb.mStep                             - ODB++ step to process
          odb.mLayer                            - ODB++ layer to process
          odb.mArgs:                            - ODB++ additional arguments. The possible additional args are:
            -out_scale:[default|sf|scale|local] :to set the out_scale mode (g2k_ver is 0)
            -show_progress                      :to show convert/rip progress
            -unit:[mm/inch]                     :set output unit (default is mm)
            -arcres:[val]                       :set arcres
            -arcsag:[val]                       :set arcsag/chord error
             
            -g2k_ver:[0|1|2|3]                  :emulation version
            -g2k_order:[0|1]                    :translation order
            -g2k_break_sr:[0|1|2]               :break SR on or off
            -g2k_scale_mode:[1|2|3]             :scaling mode
            -g2k_anchor:[0|1|2|3]               :anchor mode
            -g2k_inch_anchor:[x,y]              :anchor inch value
            -g2k_mm_anchor:[x,y]                :anchor mm value
            -g2k_offset:[0|1|2|3|4|5]           :offset mode
            -g2k_inch_offset:[x,y]              :offset inch value 
            -g2k_mm_offset:[x,y]                :offset mm value 

rip:      - RIP settings
          rip.mRam                              - Rip size of raster buffer used to hold the bitmap in memory (in MBytes)
          rip.mDPI:                             - Rip dots per inch resolution
          rip.mFMul:                            - Arc resolution fineness multiplier
          rip.mArgs:                            - Rip additional arguments. The possible additional args are:
            -extents:[LLx,LLy,URx,URy]          :extents of the incoming data to plot instead of the step's profile extents.
            -margin:[x]                         :adds a margin of x units
            -complement                         :reverses the polarity of the bitmap
            -degrees:[90|180|270|-90|-180|-270]
            -scale:[scalex,scaley]
            -mirrorx
            -mirrory

regen:    Regeneration of ODB intermediate files (must be set to true or the result of ODB_RipRegen).

Syntax

int ODB_RipSetup(const sODBSETTING& odb, const sRIPSETTING& rip, bool regen = true);

Returns

0 - success

< 0 - fail

grey:     - GREYLEVEL settings
          grey.mOutDir                          - ODB++ output directory
          grey.mStep                            - ODB++ step to process
          grey.mGreyLayerNum                    - Number of Layers
          grey.mGreyLayerList                   - List of Layers // first layer is primary layer
          grey.mGreyLevel                       - Grey Levels (min,max,drill)
          grey.mGreyBaseName                    - Output base name
          grey.mSuperSample                     - Super sample output [2|4|8|16]
          grey.mODBArgs:                        - Rip additional arguments. The possible additional args are:
            -out_scale:[default|sf|scale|local] :to set the out_scale mode (g2k_ver is 0)
            -show_progress                      :to show convert/rip progress
            -unit:[mm/inch]                     :set output unit (default is mm)
            -arcres:[val]                       :set arcres
            -arcsag:[val]                       :set arcsag/chord error
             
            -g2k_ver:[0|1|2|3]                  :emulation version
            -g2k_order:[0|1]                    :translation order
            -g2k_break_sr:[0|1|2]               :break SR on or off
            -g2k_scale_mode:[1|2|3]             :scaling mode
            -g2k_anchor:[0|1|2|3]               :anchor mode
            -g2k_inch_anchor:[x,y]              :anchor inch value
            -g2k_mm_anchor:[x,y]                :anchor mm value
            -g2k_offset:[0|1|2|3|4|5]           :offset mode
            -g2k_inch_offset:[x,y]              :offset inch value 
            -g2k_mm_offset:[x,y]                :offset mm value
          grey.mOutType                         - Rip output type [ODB_PCK_OUTPUT|ODB_TIF_OUTPUT|ODB_BMP_OUTPUT]
          grey.mRam                             - Rip size of raster buffer used to hold the bitmap in memory (in MBytes)
          grey.mDPI:                            - Rip dots per inch resolution
          grey.mFMul:                           - Arc resolution fineness multiplier
          grey.mRIPArgs:                        - Rip additional arguments. The possible additional args are:
            -extents:[LLx,LLy,URx,URy]          :extents of the incoming data to plot instead of the step's profile extents.
            -margin:[x]                         :adds a margin of x units
            -complement                         :reverses the polarity of the bitmap
            -degrees:[90|180|270|-90|-180|-270]
            -scale:[scalex,scaley]
            -mirrorx
            -mirrory

regen:    Regeneration of ODB intermediate files (must be set to true or the result of ODB_RipRegen).