Ethumb Client Fine Tune Setup
Ethumb » Ethumb Client

How to fine tune thumbnail generation, setting size, aspect, orientation, frames, quality and so on. More...

## Functions

EAPI void | ethumb_client_fdo_set (Ethumb_Client *client, Ethumb_Thumb_FDO_Size s)
| Configure future requests to use FreeDesktop.Org preset.
EAPI void | ethumb_client_size_set (Ethumb_Client *client, int tw, int th)
| Configure future request to use custom size.
EAPI void | ethumb_client_size_get (const Ethumb_Client *client, int *tw, int *th)
| Retrieve future request to use custom size.
EAPI void | ethumb_client_format_set (Ethumb_Client *client, Ethumb_Thumb_Format f)
| Configure format to use for future requests.
EAPI Ethumb_Thumb_Format | ethumb_client_format_get (const Ethumb_Client *client)
| Retrieve format to use for future requests.
EAPI void | ethumb_client_aspect_set (Ethumb_Client *client, Ethumb_Thumb_Aspect a)
| Configure aspect mode to use.
EAPI Ethumb_Thumb_Aspect | ethumb_client_aspect_get (const Ethumb_Client *client)
| Get current aspect in use for requests.
EAPI void | ethumb_client_orientation_set (Ethumb_Client *client, Ethumb_Thumb_Orientation o)
| Configure orientation to use for future requests.
EAPI Ethumb_Thumb_Orientation | ethumb_client_orientation_get (const Ethumb_Client *client)
| Get current orientation in use for requests.
EAPI void | ethumb_client_crop_align_set (Ethumb_Client *client, float x, float y)
| Configure crop alignment in use for future requests.
EAPI void | ethumb_client_crop_align_get (const Ethumb_Client *client, float *x, float *y)
| Get current crop alignment in use for requests.
EAPI void | ethumb_client_quality_set (Ethumb_Client *client, int quality)
| Configure quality to be used in thumbnails.
EAPI int | ethumb_client_quality_get (const Ethumb_Client *client)
| Get quality to be used in thumbnails.
EAPI void | ethumb_client_compress_set (Ethumb_Client *client, int compress)
| Configure compression level used in requests.
EAPI int | ethumb_client_compress_get (const Ethumb_Client *client)
| Get compression level used in requests.
EAPI Eina_Bool | ethumb_client_frame_set (Ethumb_Client *client, const char *file, const char *group, const char *swallow)
| Set frame to apply to future thumbnails.
EAPI void | ethumb_client_dir_path_set (Ethumb_Client *client, const char *path)
| Configure where to store thumbnails in future requests.
EAPI const char * | ethumb_client_dir_path_get (const Ethumb_Client *client)
| Get base directory path where to store thumbnails.
EAPI void | ethumb_client_category_set (Ethumb_Client *client, const char *category)
| Category directory to store thumbnails.
EAPI const char * | ethumb_client_category_get (const Ethumb_Client *client)
| Get category sub-directory where to store thumbnails.
EAPI void | ethumb_client_video_time_set (Ethumb_Client *client, float time)
| Set the video time (duration) in seconds.
EAPI void | ethumb_client_video_start_set (Ethumb_Client *client, float start)
| Set initial video position to start thumbnailing, in percentage.
EAPI void | ethumb_client_video_interval_set (Ethumb_Client *client, float interval)
| Set the video frame interval, in seconds.
EAPI void | ethumb_client_video_ntimes_set (Ethumb_Client *client, unsigned int ntimes)
| Set the number of frames to thumbnail.
EAPI void | ethumb_client_video_fps_set (Ethumb_Client *client, unsigned int fps)
| Set the number of frames per second to thumbnail the video.
EAPI void | ethumb_client_document_page_set (Ethumb_Client *client, unsigned int page)
| Set the page number to thumbnail in paged documents.
EAPI void | ethumb_client_ethumb_setup (Ethumb_Client *client)
| Send setup to server.
EAPI void | ethumb_client_thumb_path_set (Ethumb_Client *client, const char *path, const char *key)
| Set a defined path and key to store the thumbnail.
EAPI void | ethumb_client_thumb_path_get (Ethumb_Client *client, const char **path, const char **key)
| Get the configured thumbnail path.

## Detailed Description

How to fine tune thumbnail generation, setting size, aspect, orientation, frames, quality and so on.

## Function Documentation

## ethumb_client_fdo_set()

EAPI void ethumb_client_fdo_set | ( | Ethumb_Client * | client,
|  | Ethumb_Thumb_FDO_Size | s )

Configure future requests to use FreeDesktop.Org preset.

This is a preset to provide freedesktop.org (fdo) standard compliant thumbnails. That is, files are stored as JPEG under ~/.thumbnails/SIZE, with size being either normal (128x128) or large (256x256).

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  s | size identifier, either ETHUMB_THUMB_NORMAL (0) or ETHUMB_THUMB_LARGE (1).

See also
  ethumb_client_size_set()
  ethumb_client_aspect_set()
  ethumb_client_crop_align_set()
  ethumb_client_category_set()
  ethumb_client_dir_path_set()

References EINA_SAFETY_ON_NULL_RETURN, and ethumb_dup().

## ethumb_client_size_set()

EAPI void ethumb_client_size_set | ( | Ethumb_Client * | client,
|  | int | tw,
|  | int | th )

Configure future request to use custom size.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  tw | width, default is 128.
  th | height, default is 128.

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_thumb_size_set().

## ethumb_client_size_get()

EAPI void ethumb_client_size_get | ( | const Ethumb_Client * | client,
|  | int * | tw,
|  | int * | th )

Retrieve future request to use custom size.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  tw | where to return width. May be `NULL`.
  th | where to return height. May be `NULL`.

References EINA_SAFETY_ON_NULL_RETURN, and ethumb_thumb_size_get().

## ethumb_client_format_set()

EAPI void ethumb_client_format_set | ( | Ethumb_Client * | client,
|  | Ethumb_Thumb_Format | f )

Configure format to use for future requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  f | format identifier to use, either ETHUMB_THUMB_FDO (0), ETHUMB_THUMB_JPEG (1) or ETHUMB_THUMB_EET (2). Default is FDO.

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_thumb_format_set().

## ethumb_client_format_get()

EAPI Ethumb_Thumb_Format ethumb_client_format_get | ( | const Ethumb_Client * | client | ) |

Retrieve format to use for future requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)

Returns
  format identifier to use, either ETHUMB_THUMB_FDO (0), ETHUMB_THUMB_JPEG (1) or ETHUMB_THUMB_EET (2).

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_thumb_format_get().

## ethumb_client_aspect_set()

EAPI void ethumb_client_aspect_set | ( | Ethumb_Client * | client,
|  | Ethumb_Thumb_Aspect | a )

Configure aspect mode to use.

If aspect is kept (ETHUMB_THUMB_KEEP_ASPECT), then image will be rescaled so the largest dimension is not bigger than it's specified size (see ethumb_client_size_get()) and the other dimension is resized in the same proportion. Example: size is 256x256, image is 1000x500, resulting thumbnail is 256x128.

If aspect is ignored (ETHUMB_THUMB_IGNORE_ASPECT), then image will be distorted to match required thumbnail size. Example: size is 256x256, image is 1000x500, resulting thumbnail is 256x256.

If crop is required (ETHUMB_THUMB_CROP), then image will be cropped so the smallest dimension is not bigger than its specified size (see ethumb_client_size_get()) and the other dimension will overflow, not being visible in the final image. How it will overflow is speficied by ethumb_client_crop_align_set() alignment. Example: size is 256x256, image is 1000x500, crop alignment is 0.5, 0.5, resulting thumbnail is 256x256 with 250 pixels from left and 250 pixels from right being lost, that is just the 500x500 central pixels of image will be considered for scaling.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  a | aspect mode identifier, either ETHUMB_THUMB_KEEP_ASPECT (0), ETHUMB_THUMB_IGNORE_ASPECT (1) or ETHUMB_THUMB_CROP (2).

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_thumb_aspect_set().

## ethumb_client_aspect_get()

EAPI Ethumb_Thumb_Aspect ethumb_client_aspect_get | ( | const Ethumb_Client * | client | ) |

Get current aspect in use for requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)

Returns
  aspect in use for future requests.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_thumb_aspect_get().

## ethumb_client_orientation_set()

EAPI void ethumb_client_orientation_set | ( | Ethumb_Client * | client,
|  | Ethumb_Thumb_Orientation | o )

Configure orientation to use for future requests.

Default value is ETHUMB_THUMB_ORIENT_ORIGINAL: metadata from the file will be used to orient pixel data.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  o | format identifier to use, either ETHUMB_THUMB_ORIENT_NONE (0), ETHUMB_THUMB_ROTATE_90_CW (1), ETHUMB_THUMB_ROTATE_180 (2), ETHUMB_THUMB_ROTATE_90_CCW (3), ETHUMB_THUMB_FLIP_HORIZONTAL (4), ETHUMB_THUMB_FLIP_VERTICAL (5), ETHUMB_THUMB_FLIP_TRANSPOSE (6), ETHUMB_THUMB_FLIP_TRANSVERSE (7) or ETHUMB_THUMB_ORIENT_ORIGINAL (8). Default is ORIGINAL.

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_thumb_orientation_set().

## ethumb_client_orientation_get()

EAPI Ethumb_Thumb_Orientation ethumb_client_orientation_get | ( | const Ethumb_Client * | client | ) |

Get current orientation in use for requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)

Returns
  orientation in use for future requests.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_thumb_orientation_get().

## ethumb_client_crop_align_set()

EAPI void ethumb_client_crop_align_set | ( | Ethumb_Client * | client,
|  | float | x,
|  | float | y )

Configure crop alignment in use for future requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  x | horizontal alignment. 0.0 means left side will be visible or right side is being lost. 1.0 means right side will be visible or left side is being lost. 0.5 means just center is visible, both sides will be lost. Default is 0.5.
  y | vertical alignment. 0.0 is top visible, 1.0 is bottom visible, 0.5 is center visible. Default is 0.5

References EINA_SAFETY_ON_NULL_RETURN, and ethumb_dup().

## ethumb_client_crop_align_get()

EAPI void ethumb_client_crop_align_get | ( | const Ethumb_Client * | client,
|  | float * | x,
|  | float * | y )

Get current crop alignment in use for requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  x | where to return horizontal alignment. May be `NULL`.
  y | where to return vertical alignment. May be `NULL`.

References EINA_SAFETY_ON_NULL_RETURN.

## ethumb_client_quality_set()

EAPI void ethumb_client_quality_set | ( | Ethumb_Client * | client,
|  | int | quality )

Configure quality to be used in thumbnails.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  quality | value from 0 to 100, default is 80. The effect depends on the format being used, PNG will not use it.

References EINA_SAFETY_ON_NULL_RETURN, and ethumb_thumb_quality_set().

## ethumb_client_quality_get()

EAPI int ethumb_client_quality_get | ( | const Ethumb_Client * | client | ) |

Get quality to be used in thumbnails.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)

Returns
  quality value from 0 to 100, default is 80. The effect depends on the format being used, PNG will not use it.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_thumb_quality_get().

## ethumb_client_compress_set()

EAPI void ethumb_client_compress_set | ( | Ethumb_Client * | client,
|  | int | compress )

Configure compression level used in requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  compress | value from 0 to 9, default is 9. The effect depends on the format being used, JPEG will not use it.

References EINA_SAFETY_ON_NULL_RETURN, and ethumb_thumb_compress_set().

## ethumb_client_compress_get()

EAPI int ethumb_client_compress_get | ( | const Ethumb_Client * | client | ) |

Get compression level used in requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)

Returns
  compress value from 0 to 9, default is 9. The effect depends on the format being used, JPEG will not use it.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_thumb_compress_get().

## ethumb_client_frame_set()

EAPI Eina_Bool ethumb_client_frame_set | ( | Ethumb_Client * | client,
|  | const char * | file,
|  | const char * | group,
|  | const char * | swallow )

Set frame to apply to future thumbnails.

This will create an edje object that will have image swallowed in. This can be used to simulate Polaroid or wood frames in the generated image. Remeber it is bad to modify the original contents of thumbnails, but sometimes it's useful to have it composited and avoid runtime overhead.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  file | file path to edje.
  group | group inside edje to use.
  swallow | name of swallow part.

Returns
  `EINA_TRUE` on success, `EINA_FALSE` on failure.

References EINA_SAFETY_ON_NULL_RETURN_VAL, ethumb_dup(), and ethumb_frame_set().

## ethumb_client_dir_path_set()

EAPI void ethumb_client_dir_path_set | ( | Ethumb_Client * | client,
|  | const char * | path )

Configure where to store thumbnails in future requests.

This value will be used to generate thumbnail paths, that is, it will be used when ethumb_client_thumb_path_set() was not called after last ethumb_client_file_set().

Note that this is the base, a category is added to this path as a sub directory. This is not the final directory where files are stored, the thumbnail system will account category as well, see ethumb_client_category_set().

As other options, this value will only be applied to future requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  path | base directory where to store thumbnails. Default is ~/.thumbnails

See also
  ethumb_client_category_set()

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_thumb_dir_path_set().

## ethumb_client_dir_path_get()

EAPI const char * ethumb_client_dir_path_get | ( | const Ethumb_Client * | client | ) |

Get base directory path where to store thumbnails.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)

Returns
  pointer to internal string with current path. This string should not be modified or freed.

See also
  ethumb_client_dir_path_set()

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_thumb_dir_path_get().

## ethumb_client_category_set()

EAPI void ethumb_client_category_set | ( | Ethumb_Client * | client,
|  | const char * | category )

Category directory to store thumbnails.

This value will be used to generate thumbnail paths, that is, it will be used when ethumb_client_thumb_path_set() was not called after last ethumb_client_file_set().

This is a sub-directory inside base directory (ethumb_client_dir_path_set()) that creates a namespace to avoid different options resulting in the same file.

As other options, this value will only be applied to future requests.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  category | category sub directory to store thumbnail. Default is either "normal" or "large" for FDO compliant thumbnails or WIDTHxHEIGHT-ASPECT[-FRAMED]-FORMAT. It can be a string or `NULL` to use auto generated names.

See also
  ethumb_client_dir_path_set()

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_thumb_category_set().

## ethumb_client_category_get()

EAPI const char * ethumb_client_category_get | ( | const Ethumb_Client * | client | ) |

Get category sub-directory where to store thumbnails.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)

Returns
  pointer to internal string with current path. This string should not be modified or freed.

See also
  ethumb_client_category_set()

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_thumb_category_get().

## ethumb_client_video_time_set()

EAPI void ethumb_client_video_time_set | ( | Ethumb_Client * | client,
|  | float | t )

Set the video time (duration) in seconds.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  t | duration (in seconds). Defaults to 3 seconds.

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_video_time_set().

## ethumb_client_video_start_set()

EAPI void ethumb_client_video_start_set | ( | Ethumb_Client * | client,
|  | float | start )

Set initial video position to start thumbnailing, in percentage.

This is useful to avoid thumbnailing the company/producer logo or movie opening.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  start | initial video positon to thumbnail, in percentage (0.0 to 1.0, inclusive). Defaults to 10% (0.1).

References EINA_SAFETY_ON_FALSE_RETURN, EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_video_start_set().

## ethumb_client_video_interval_set()

EAPI void ethumb_client_video_interval_set | ( | Ethumb_Client * | client,
|  | float | interval )

Set the video frame interval, in seconds.

This is useful for animated thumbnail and will define skip time before going to the next frame. Note that video backends might not be able to precisely skip that amount as it will depend on various factors, including video encoding.

Although this seems similar to ethumb_client_video_fps_set(), this one is the time that will be used to seek. The math is simple, for each new frame the video position will be set to: ((video_length * start_time) + (interval * current_frame_number)).

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  interval | time between frames, in seconds. Defaults to 0.05 seconds.

References EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_video_interval_set().

## ethumb_client_video_ntimes_set()

EAPI void ethumb_client_video_ntimes_set | ( | Ethumb_Client * | client,
|  | unsigned int | ntimes )

Set the number of frames to thumbnail.

This is useful for animated thumbnail and will define how many frames the generated file will have.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  ntimes | number of times, must be greater than zero. Defaults to 3.

References EINA_SAFETY_ON_FALSE_RETURN, EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_video_ntimes_set().

## ethumb_client_video_fps_set()

EAPI void ethumb_client_video_fps_set | ( | Ethumb_Client * | client,
|  | unsigned int | fps )

Set the number of frames per second to thumbnail the video.

This configures the number of times per seconds the thumbnail will use to create thumbnails.

Although this is similar to ethumb_client_video_interval_set(), it is the delay used between calling functions thata generates frames, while the other is the time used to skip inside the video.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  fps | number of frames per second to thumbnail. Must be greater than zero. Defaults to 10.

References EINA_SAFETY_ON_FALSE_RETURN, EINA_SAFETY_ON_NULL_RETURN, ethumb_dup(), and ethumb_video_fps_set().

## ethumb_client_document_page_set()

EAPI void ethumb_client_document_page_set | ( | Ethumb_Client * | client,
|  | unsigned int | page )

Set the page number to thumbnail in paged documents.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  page | page number, defaults to 0 (first).

References EINA_SAFETY_ON_NULL_RETURN, ethumb_document_page_set(), and ethumb_dup().

## ethumb_client_ethumb_setup()

EAPI void ethumb_client_ethumb_setup | ( | Ethumb_Client * | client | ) |

Send setup to server.

This method is called automatically by ethumb_client_generate() if any property was changed. No need to call it manually.

Parameters

  client | client instance. Must not be `NULL` and client must be connected (after connected_cb is called).

References eina_list_append(), EINA_SAFETY_ON_FALSE_RETURN, EINA_SAFETY_ON_NULL_RETURN, eldbus_message_iter_arguments_append(), eldbus_message_iter_container_close(), eldbus_message_iter_get(), eldbus_proxy_method_call_new(), eldbus_proxy_send(), ethumb_document_page_get(), ethumb_frame_get(), ethumb_thumb_aspect_get(), ethumb_thumb_category_get(), ethumb_thumb_compress_get(), ethumb_thumb_dir_path_get(), ethumb_thumb_format_get(), ethumb_thumb_orientation_get(), ethumb_thumb_quality_get(), ethumb_thumb_size_get(), ethumb_video_fps_get(), ethumb_video_interval_get(), ethumb_video_ntimes_get(), ethumb_video_start_get(), and ethumb_video_time_get().

Referenced by ethumb_client_generate().

## ethumb_client_thumb_path_set()

EAPI void ethumb_client_thumb_path_set | ( | Ethumb_Client * | client,
|  | const char * | path,
|  | const char * | key )

Set a defined path and key to store the thumbnail.

If not explicitly given, the thumbnail path will be auto-generated by ethumb_client_thumb_exists() or server using configured parameters like size, aspect and category.

Set these to `NULL` to forget previously given values. After ethumb_client_file_set() these values will be reset to `NULL`.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  path | force generated thumbnail to the exact given path. If `NULL`, then reverts back to auto-generation.
  key | force generated thumbnail to the exact given key. If `NULL`, then reverts back to auto-generation.

References EINA_SAFETY_ON_NULL_RETURN.

## ethumb_client_thumb_path_get()

EAPI void ethumb_client_thumb_path_get | ( | Ethumb_Client * | client,
|  | const char ** | path,
|  | const char ** | key )

Get the configured thumbnail path.

This returns the value set with ethumb_client_thumb_path_set() or auto-generated by ethumb_client_thumb_exists() if it was not set.

Parameters

  client | the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
  path | where to return configured path. May be `NULL`. If there was no path configured with ethumb_client_thumb_path_set() and ethumb_client_thumb_exists() was not called, then it will probably return `NULL`. If not `NULL`, then it will be a pointer to a stringshared instance, but no references are added (do it with eina_stringshare_ref())!
  key | where to return configured key. May be `NULL`. If there was no key configured with ethumb_client_thumb_key_set() and ethumb_client_thumb_exists() was not called, then it will probably return `NULL`. If not `NULL`, then it will be a pointer to a stringshared instance, but no references are added (do it with eina_stringshare_ref())!

References EINA_SAFETY_ON_NULL_RETURN.