web page header logo


List of Functions for ODB_RIP



ODB_RipInitialize

Description

The first function called (once.) It initializes the library and checks out the license.

Syntax

 int ODB_RipInit(const char* exec);

Error Codes

0 = SUCCESS

< 0 = FAIL



ODB_RipOpen

Description

This call is used to open the ODB++ file. It must be used prior to any attempt to call a raster function.

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

struct ODB_RipTree *  ODB_RipOpen 
     ( char * input, 
       char * caller, 
       char * working_dir, 
       int argc, 
       char ** argv
     );

Arguments

    input - the name of the .tgz file or the path to the top of the ODB++ directory hierarchy.

    caller - the path and file name of the calling program.

    working_dir - the path where temporary files will be written by the library.

    argc - the number of arguments in the list argv

    argv - a series of optional "engine arguments" that control the behavior of this function.

      -dbg - if present, directs the library to output additional debug info to the log file

      -nolog - if set the log file output is suppresssed

      -keep_temp_files - if set, temp files placed into the working directory are not cleaned up when the library is closed. Otherwise they are cleaned up by default.

      -thrnum:N - if not set defaults = 1. Otherwise will use multiple threads for decompressing the ODB++ data.

      -units:UNIT - UNIT is either inch or mm. Defines the units of any dimensional data passed to or from the library.


Returns

    This function returns a data structure, ODB_RipTree, describing the contents of the ODB++ file so that the calling application can display to an end user the list of steps and layers and enable the user to intelligently select the desired step and layer to rasterize.


Error Codes




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



ODB_RipSettings

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.



ODB_RipSetup

Description

This function is used to set up the rasterizer portion of ODB_RIP. Once set, these values will affect each call to ODB_RipStart.

Syntax

int ODB_RipSetup (char * step, char * layer, char * dpi, char * ram, int argc, int argv)

Arguments

    There are both mandatory and optional arguments for this function:

    Mandatory Arguments

      step - the name of the step to process

      layer - the name of the layer to process

      -dpi:DPI - where DPI is resolution in dots per inch

      OR

      -dpm:DPM - where DPM is the resolution in dots per mm

      OR

      -pixelsize:PS - where PS is the pixel size in microns

      -ram:R - size of raster buffer used to hold the bitmap in memory (in MBytes)

    Optional Arguments

    The optional arguments are placed into the argv list of strings. The argc argument tells the library how many optional arguments strings to expect.

      -extents:LLx,LLy,URx,URy   used to define the extents of the incoming data to plot. If not specified, then the program uses the default extents computed from the step's profile.

      -mirror:M[,m]   used to mirror along the X or Y axis (or both)

      -scale:S[,s]   used to scale the data. If only one parameter then it scales both X and Y equally. If two parameters the first one scales X and the second scales Y.

      -rotate:D   used to rotate the image; D must be 90,180,270

      -complement   used to reverse the polarity of the bitmap

      -vertical   directs the program to run the bands vertically instead of horizontally

      -bitmap_clip_dim:M   used to define the "width" of the band instead of the library computing the width based on the DPI, the image size and the memory allocated for the image.

      -bitmap_clip_dim:M,N   used to precisely define the width and the length of the band. This is often used in order to force a band to match the physical number of elements in an LED array or other such printing device.

      -top_edge_golden   by default the top and left edges are golden.

      -bottom_edge_golden

      -right_edge_golden

      -left_edge_golden

      -thrnum   number of CPU threads that can be used simultaneously for rasterizing


    Error Codes




ODB_RipStart

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 1000000.

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

    This function should be called for the first time after ODB_RipSetup or each time ODB_RipWait returns _RIP_BAND_COMPLETE.

Syntax

    int ODB_RipStart(unsigned char* MemoryChunkPointer);

Arguments

    MemoryChunkPointer - Pointer to the memory buffer that will be used to store a band of the rasterized image. This memory buffer belongs to the calling program.


Error Codes

    0 = success

    GR_ERR_INVINPUT

    GR_ERR_CLOSE

    GR_ERR_INVOPR

    GR_ERR_MUTEXH




ODB_RipWaitForBand

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.

    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(int MaxWaitTime);

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)




ODB_RipGetStatus

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)




ODB_RipGetProgress

Description

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

Syntax

    int ODB_RipGetProgress(CGRProgress& CurrProgress)

Arguments

    Reference to CGRProgress object to store information


Returns

    Success 0

    Error _GR_ERROR_MUTEXH



ODB_RipGetRipImage

Description

    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 ODB_Rip library rasterizes only one Band irrespective of the number of memory buffers available for the rasterization process.

Syntax

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

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)

    _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.



ODB_RipGetNumberOfBands

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)




ODB_RipCancel

Description

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

Syntax

    int ODB_RipCancel();

Returns

    0 (always)




ODB_RipExit

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)




ODB_RipGetVersion

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






ARTWORK CONVERSION SOFTWARE, INC.                  Company Profile
417 Ingalls St.,     Santa Cruz, CA 95060         Tel (831) 426-6163     Fax 426-2824               email: info@artwork.com