libcasio/docs/user/picture.rst

Picture management
==================

libcasio manages picture formats.

The pixel
---------

.. c:type:: casio_pixel_t

	A pixel represented as a 32-bit integer, encoded as 0x00RRGGBB using
	native endianness, which is used as the canonical form of representing
	a picture in libcasio.

.. c:function:: casio_pixel_t casio_pixel(int r, int g, int b)

	Function-like macro to create a pixel.

.. c:function:: casio_pixel_t casio_pixel_with_r(casio_pixel_t pix, int r)

	Replace the red component of a pixel with the given value.

.. c:function:: casio_pixel_t casio_pixel_with_g(casio_pixel_t pix, int g)

	Replace the green component of a pixel with the given value.

.. c:function:: casio_pixel_t casio_pixel_with_b(casio_pixel_t pix, int b)

	Replace the blue component of a pixel with the given value.

.. c:function:: int casio_pixel_r(casio_pixel_t pix)

	Get the red component of a pixel.

.. c:function:: int casio_pixel_g(casio_pixel_t pix)

	Get the green component of a pixel.

.. c:function:: int casio_pixel_b(casio_pixel_t pix)

	Get the blue component of a pixel.

Picture encodings
-----------------

.. c:type:: casio_colorcode_t

	Color codes for the :c:macro:`casio_pictureformat_4bit_code` picture
	encoding.

	.. c:macro:: casio_colorcode_black

		Black: 0x000000.

	.. c:macro:: casio_colorcode_blue

		Blue: 0x0000FF.

	.. c:macro:: casio_colorcode_green

		Green: 0x00FF00.

	.. c:macro:: casio_colorcode_cyan

		Cyan: 0x00FFFF.

	.. c:macro:: casio_colorcode_red

		Red: 0xFF0000.

	.. c:macro:: casio_colorcode_magenta

		Magenta: 0xFF00FF.

	.. c:macro:: casio_colorcode_yellow

		Yellow: 0xFFFF00.

	.. c:macro:: casio_colorcode_white

		White: 0xFFFFFF.

.. c:type:: casio_pictureformat_t

	The picture format type.

	By default, the pixels of a picture are defined top to bottom, left to
	right.

	.. c:macro:: casio_pictureformat_1bit

		In this format, each bit represents a pixel (so one byte contains
		eight pixels). If the width is not divisible by eight, then the
		last bits of the last byte of the line are unused (fill bits), and
		the next line starts at the beginning of the next byte; this makes
		the navigation between lines easier, but takes up more space.

		An off bit (0b0) represents a white pixel, and an on bit (0b1)
		represents a black pixel.

		For calculating the size of such pictures, calculate the
		number of bytes a line occupies (usually ``ceil(w / 8)``)
		and multiply it by the number of lines.

	.. c:macro:: casio_pictureformat_1bit_r

		Same as :c:macro:`casio_pictureformat_1bit`, except an off bit (0b0)
		represents a black pixel, and an on bit (0b1) represents a white
		pixel.

	.. c:macro:: casio_pictureformat_1bit_packed

		Packed monochrome pictures are basically the same as the format
		described for :c:macro:`casio_pictureformat_1bit`, except there
		are no fill bits: if a picture width is 6 pixels, then the second
		line will start at the seventh bit of the first byte (where it
		would start at the first bit of the second byte with fill bits).

		The navigation to a line is less easy as it takes at least one
		division.

		For calculating the size of such pictures, calculate the
		total number ``P`` of pixels (``w * h``) and divide it by
		the size of a byte (``ceil(p / 8)``).

	.. c:macro:: casio_pictureformat_1bit_packed_r

		Same as :c:macro:`casio_pictureformat_1bit_packed`, with the
		differences described in :c:macro:`casio_pictureformat_1bit_r`.

	.. c:macro:: casio_pictureformat_1bit_old

		The old monochrome format used by CASIO is basically a normal
		monochrome format (the width is usually 96 or 128, so no need for
		fill bits), except that it starts with the last byte (where the
		bits are in left to right), but it goes right to left,
		bottom to top.

		The size is the same as for :c:macro:`casio_pictureformat_1bit`,
		except the byte order changes.

	.. c:macro:: casio_pictureformat_2bit_dual

		This is the format used for the Prizm's projector mode. It is
		composed of two monochrome pictures (with sizes divisible by
		eight). It is basically gray pictures, with white, gray, dark gray
		and black.

		To calculate the size, well, just multiply the size of such a
		picture in the :c:macro:`casio_pictureformat_1bit` per 2.

	.. c:macro:: casio_pictureformat_4bit

		This is a 4 bit per pixel format. There is no need for fill nibbles.
		Each nibble (group of 4 bits) is made of the following:

		- one bit for red (OR by 0xFF0000).
		- one bit for green (OR by 0x00FF00).
		- one bit for blue (OR by 0x0000FF).
		- one alignment bit.

		To calculate the size, divide the number of pixels (``w * h``) by 2.

	.. c:macro:: casio_pictureformat_4bit_code

		In this encoding, each nibble for a pixel represents one of the
		colors defined in :c:type:`casio_colorcode_t` or, in case of an
		illegal value (8 and above), plain black.

		The size is calculated the same way as for
		:c:macro:`casio_pictureformat_4bit`.

	.. c:macro:: casio_pictureformat_4bit_color

		This format is used by old CASIO models. It is made of four monochrome
		pictures (no need for fill bits), where the palettes are orange,
		green, blue, white (bg).

		To get the size, just multiply the size of a VRAM (see
		:c:macro:`casio_pictureformat_1bit`) by 4.

	.. c:macro:: casio_pictureformat_4bit_mono

		Same as :c:macro:`casio_pictureformat_4bit_color`, except the
		palette are (unused), (unused), black, white (bg).

	.. c:macro:: casio_pictureformat_casemul

		This format is used by CasEmul. It is basically arbitrary color codes,
		1 byte per code, where, for example, 1 is orange. You can check the
		full color codes in ``lib/picture.c``.

		The size in bytes is the number of pixels.

	.. c:macro:: casio_pictureformat_16bit

		This format is used for the Prizm's VRAM. Each pixel is two bytes
		long, where:

		- the first five bytes represents the high five (clap!) bits of
		  the red part.
		- the next six bits represent the high six bits of the green part.
		- the last five bits represent the high five (re-clap!) bits of
		  the blue part.

		The size in bytes is the number of pixels times 2.

Managing a picture
------------------

You cannot make a picture directly, you have to decode it.

.. c:function:: void casio_free_picture(casio_picture_t *picture)

	Free the picture. Any related resource (such as the pixel matrix)
	will also be free'd, so be careful.

.. c:function:: int casio_get_picture_dimensions(casio_picture_t *picture, \
	unsigned int *widthp, unsigned int *heightp)

	Get the picture width and height.

.. c:function:: int casio_access_pixels(casio_picture_t *picture, \
	casio_pixel_t ***pixels)

	Access the pixels as a pixel matrix.

Encoding and decoding a picture
-------------------------------

.. c:function:: int casio_decode_picture(casio_picture_t **picturep, \
	unsigned int width, unsigned int height, \
	casio_pictureformat_t format, tio_stream_t *stream)

	Create a picture out of a readable stream, with the width and height.

.. c:function:: int casio_decode_picture_buffer(casio_picture_t **picturep, \
	unsigned int width, unsigned int height, \
	casio_pictureformat_t format, void const *data, size_t data_size)

	Create a picture out of raw data, with the width and height.

.. c:function:: int casio_get_picture_encoded_size(casio_picture_t *picture, \
	casio_pictureformat_t format, size_t *sizep)

	Get the required size for encoding the picture in a given format.

.. c:function:: int casio_encode_picture(casio_picture_t *picture, \
	casio_pictureformat_t format, void *buf, size_t size)

	Get the encoded form of a picture, using a given format and encoding
	into the given buffer.