Pegasus

The Pegasus function is the single entry point into the image-manipulation operations provided by PICTools. The specific image operation requested is indicated by the value of the PicParm->Op field containing the operation's opcode.

	Copy Code
RESPONSE *Pegasus(PIC_PARM PICFAR PicParm, REQUEST Request)**

Parameters:

Name

Description

PicParm

Identifies the operation to perform, specifies additional input and output parameters for the operation and specifies the input and output image buffers (the Get and Put queues). For additional information, see the description of the PIC_PARM structure in the PICTools Structures section.

Request

Specifies the request to perform. It has one of the following values:

Value	Meaning
REQ_CONT	Resumes execution of the operation which was paused when Pegasus returned an operation event (legacy mode only).
REQ_EXEC	Begins execution of the operation. Please note that any error condition or warning Status returnedduring REQ_INIT may be overwritten during REQ_EXEC and therefore the application should save it if needed, before calling REQ_EXEC.
REQ_INIT	Begins initialization of the operation. Internal memory allocation and other initialization takes place.
REQ_TERM	Terminates the operation. The operation may be terminated at any time. All internally-allocated memory is freed. When Pegasus returns an error (RES_ERR response), the operation is already terminated and REQ_TERM is not needed.

Return Value:

The returned response from Pegasus is one of the following values. When a response is only returned for some operations, additional useful information may be found in the description of the operation and of the operation structure.

Value	Meaning
RES_ALLOCATE_APP2_BUF	An APP2 marker was encountered in the image and AppFieldSize was set to -1 in the operation structure. The application should allocate an AppFieldLen size buffer for the APP2 data. This response can occur after REQ_INIT, but does not occur after REQ_EXEC. It may be returned by the OP_S2D and OP_P2D opcodes.
RES_ALLOCATE_COMMENT_BUF	A comment was encountered in the image and PF_AllocateComment was set in the PicFlags field in the operation structure. The application should allocate a CommentLen size buffer for the comment. This response can occur after REQ_INIT or after REQ_EXEC or after both. It may be returned by the OP_S2D and OP_P2D opcodes.
RES_AUX_NEEDED	Auxiliary image data was encountered in the image and it was too large for the value of the AuxSize field in the operation structure. The application should allocate a larger buffer. This response can occur after REQ_INIT or after REQ_EXEC. It is only returned by the OP_F2D and OP_F2DPLUS opcodes.
RES_COLORS_MADE	PF_MakeColors was set in PicFlags in the operation structure and an optimum color table has been made. The application can now make use of the color table. For example, a palette based on the color table can be created and realized before DIB pixels based on the color table are returned.. This response only occurs after REQ_EXEC. It is only returned by the OP_S2D and OP_P2D group of opcodes.
RES_DONE	The operation was completed without error. This response occurs after REQ_INIT and after REQ_EXEC.
RES_ERR	An error occurred. Examine Status in the PIC_PARM data for an error code. The operation is terminated.
RES_EXTEND_PIC2LIST	Comment or other data has been encountered in the input image and PIC2ListSize is not 0 and PIC2ListSize - PIC2ListLen indicates there is not enough space in the PIC2List buffer to hold all of the data. When RES_EXTEND_PIC2LIST is returned, PIC2ListLen has been set to the new PIC2ListSize required for the PIC2List buffer in order to hold all of the encountered data. PacketType has the PIC2List packet type for the data so the application can decide whether or not it cares. Ordinarily, the application will reallocate PIC2List to be PIC2ListLen bytes long and will set PIC2ListSize equal to PIC2ListLen before returning from DeferFn.
RES_GET_DATA_YIELD	PF_YieldGet was specified in PicFlags in the operation structure and an additional portion of the Get queue was consumed. This response does not indicate the Get queue is empty. The application may perform any other desired processing. This response can occur after REQ_INIT and after REQ_EXEC.
RES_GET_NEED_DATA	The Get queue has not been allocated or doesn't contain enough data to continue the operation. The application must allocate a buffer for the Get queue, if necessary, and must add data to the Get queue before resuming the operation. This response can occur after REQ_INIT and after REQ_EXEC.
RES_HAVE_COMMENT	A comment was encountered in the image data and PF_AllocateComment was set in PicFlags in the operation structure and the PIC_PARM CommentLen field is not 0. The fact that CommentLen is not 0 indicates that this comment is not the first comment in the image data. The application should save the previous comment's data before it is overwritten by the new comment. After the operation is resumed, Pegasus will immediately return a RES_ALLOCATE_COMMENT_BUF response to allow the application to allocate a buffer for the new comment's data. This response can occur after REQ_INIT or after REQ_EXEC or after both. It may be returned by the OP_S2D and OP_P2D opcodes.
RES_NULL_PICPARM_PTR	A NULL PIC_PARM pointer was passed to the Pegasus routine. This indicates an error in programming.
RES_POKE	Data needs to be poked into a prior location in the output image, and that location is no longer present in the Put queue. This will only occur after all other, sequential, output has been placed in the Put queue. SeekInfo has the offset in the output image to poke the data. The data extends sequentially (no wrap-around) from Put.FrontEnd. The length of the data is Put.RearEnd - Put.FrontEnd. RES_POKE is intended to be optional and the output image is still correct. RES_POKE's are intended to occur after all other sequential or RES_SEEK'ed output has occurred. RES_POKE is a combination of seek/write in one response/operation and the write is ordinarily a small number of bytes, like a DWORD.
RES_PUT_DATA_YIELD	PF_YieldPut was specified in PicFlags in the operation structure and some additional data was placed in the Put queue. This response does not indicate the Put queue is full. The application should perform any desired processing. This response can occur after REQ_INIT and after REQ_EXEC. It is recommended that you do not change the PUT queue pointers in response to this message.
RES_PUT_NEED_SPACE	There is additional output data available, but the Put queue isn't allocated or doesn't have enough room for the additional output data. The application must allocate a buffer for the Put queue, if necessary, or remove data from the Put queue before resuming the operation. This response can occur after REQ_INIT and after REQ_EXEC. Note that RES_PUT_NEED_SPACE is not returned after the last operation output data is placed in the queue. You should check the Put queue after the operation is complete to see if additional output data has been produced.
RES_SEEK	The Get queue or Put queue must be repositioned to a non-contiguous location in the input or output image. This response can only occur after REQ_EXEC. It may be returned by the OP_F2D, OP_F2DPLUS, OP_D2F, OP_D2FPLUS or OP_UTL opcodes. RES_SEEK is an indication ordinarily that substantial sequential output from the new location is expected. Ordinarily RES_SEEK in the Put queue would occur when reading an existing image through the Put queue for a multi-image append.
RES_YIELD	This response is not currently returned by any opcodes.
RES_QUERY	NA for PICTools. This response is used by the ScanFix opcode for each object found during certain object detection operations. The calling function provides a structure with information about the object in question, and will keep or remove the object based on the data returned in the structure.

Errors:

If the RES_ERR response is returned, examine Status in the PIC_PARM structure to determine the error value. See the ERRORS.H file for descriptive names for each error code, except for -1. When an error code of -1 is returned, a low-level Pegasus routine has detected an error which was almost certainly caused by invalid image data. It can be most correctly treated as identical to ERR_BAD_DATA.