xil_cis_has_data(3)

NAME

xil_cis_has_data, xil_cis_has_frame, xil_cis_number_of_frames − determine number of bytes or frames in a compressed image sequence

SYNOPSIS

#include <xil/xil.h>

int xil_cis_has_data (XilCis cis);

Xil_boolean xil_cis_has_frame (XilCis cis);

int xil_cis_number_of_frames (XilCis cis);

DESCRIPTION

xil_cis_has_data () determines how many bytes of compressed data the compressed image sequence cis contains. This number reflects the number of bytes from the current read frame in the compressed image sequence (CIS) to the end of the CIS.

The number includes any bytes in an uncompleted frame at the end of a CIS. If the number of bytes is greater than zero, you can get a pointer to the data in the CIS by calling xil_cis_get_bits_ptr(3). However, you may not be able to read all of the data from the CIS at one time, because that data may not be in one contiguous buffer.

Also note that if all data has been retrieved from the CIS except for an incomplete frame at the CIS’s end, xil_cis_has_data() returns a value greater than zero even though xil_cis_get_bits_ptr(3) will not be able to retrieve the data, because the last frame is not complete.

xil_cis_has_frame() returns TRUE if a complete frame exists at the read frame position, and returns FALSE otherwise. This routine can be used before calls such as xil_decompress(3) and xil_cis_get_bits_ptr(3) to test whether data is available for the desired operation. It is generally a better test than xil_cis_has_data() or xil_cis_number_of_frames() for determining the existence of data at the read frame position.

xil_cis_number_of_frames() determines how many complete frames of compressed data the compressed image sequence cis contains. This number reflects the number of frames from the current read position in the CIS to the last complete frame in the CIS. If a user inserts an unknown or partial number of frames in an XilCis, then the decompresser must parse the data to determine how many frames are in the XilCis. This can make xil_cis_number_of_frames() potentially expensive if called after either xil_cis_put_bits(3) or xil_cis_put_bits_ptr(3) have supplied a partial frame or an unknown number of frames.

RETURN VALUES

xil_cis_has_data() returns the number of bytes from the current read frame in the CIS to end of the CIS.

xil_cis_has_frame() returns TRUE if a complete frame exists at the read position; otherwise, FALSE.

xil_cis_number_of_frames() returns the number of frames from the current read frame in the CIS to end of the CIS.

ERRORS

For a complete list of XIL error messages by number, consult Appendix B of the XIL Programmer’s Guide.

EXAMPLES

This example demonstrates that you can use any of three routines to determine if there are any frames in the CIS. Note that if all you are trying to do is determine if any frames are left in a CIS, then xil_cis_has_frame() is the preferred routine for accomplishing this.

The following loops extract all the bits between (and including) the read frame and the end of the CIS. In this example, nothing is done with the bits that are extracted. As it stands, if a partial frame exists at the end of the CIS, the xil_cis_has_data() loop never terminates.

XilCis cis;
char∗ data;
int nframes;
int nbytes;
while (xil_cis_number_of_frames(cis))
      data = (char ∗)xil_cis_get_bits_ptr(cis, &nbytes, &nframes);
while (xil_cis_has_data(cis))
      data = (char ∗)xil_cis_get_bits_ptr(cis, &nbytes, &nframes);
while (xil_cis_has_frame(cis))
      data = (char ∗)xil_cis_get_bits_ptr(cis, &nbytes, &nframes);

Museum

Related Articles